Send traces with OpenTelemetry (OTLP)

If your app already uses OpenTelemetry (OTel), you can send its traces straight to Glassray. Point your OTel exporter at Glassray’s endpoint, add an API key, and tag your traces. You don’t need the Glassray SDK.

Not using OpenTelemetry yet? For JavaScript and TypeScript, the @glassray/tracing SDK is quicker to set up. It sends to the same endpoint without any OTel setup.

Setup

Create an API key

In Glassray, go to Settings → Sources and add an OpenTelemetry source. Copy the API key it shows you. You only see it once.Store it where your app can read it, for example as the environment variable GLASSRAY_API_KEY.

Set up OTel and point it at Glassray

Set up the OTel SDK once, when your app starts. Its exporter needs two things: Glassray’s URL, https://app.glassray.ai/api/public/otel/v1/traces, and the header Authorization: Bearer <your-api-key>.

Node.js
Python
Ruby

npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/exporter-trace-otlp-proto @opentelemetry/resources

tracing.ts

import { BatchSpanProcessor, NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { resourceFromAttributes } from "@opentelemetry/resources";

export const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    "service.name": "support-bot",
    "glassray.agent": "support-bot",
  }),
  spanProcessors: [
    new BatchSpanProcessor(
      new OTLPTraceExporter({
        url: "https://app.glassray.ai/api/public/otel/v1/traces",
        headers: { Authorization: `Bearer ${process.env.GLASSRAY_API_KEY}` },
      }),
    ),
  ],
});

provider.register();

Before a script exits, call await provider.shutdown(). In a serverless function, call await provider.forceFlush() at the end of each request. Otherwise the last batch of spans is lost.This exporter sends protobuf. @opentelemetry/exporter-trace-otlp-http sends JSON, and works the same way.

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

tracing.py

import os

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider(
    resource=Resource.create({
        "service.name": "support-bot",
        "glassray.agent": "support-bot",
    })
)
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://app.glassray.ai/api/public/otel/v1/traces",
            headers={"Authorization": f"Bearer {os.environ['GLASSRAY_API_KEY']}"},
        )
    )
)
trace.set_tracer_provider(provider)

Before a script exits, call provider.shutdown(). Otherwise the last batch of spans is lost.

Gemfile

gem "opentelemetry-sdk"
gem "opentelemetry-exporter-otlp"

In Rails, put this in an initializer such as config/initializers/opentelemetry.rb:

require "opentelemetry/sdk"
require "opentelemetry/exporter/otlp"

OpenTelemetry::SDK.configure do |c|
  c.service_name = "support-bot"
  c.resource = OpenTelemetry::SDK::Resources::Resource.create(
    "glassray.agent" => "support-bot"
  )
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: "https://app.glassray.ai/api/public/otel/v1/traces",
        headers: { "Authorization" => "Bearer #{ENV.fetch("GLASSRAY_API_KEY")}" }
      )
    )
  )
end

Before a script exits, call OpenTelemetry.tracer_provider.shutdown. Otherwise the last batch of spans is lost.

Prefer environment variables? You can leave the URL and key out of the code and set them as environment variables instead. The names are the same in every language:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://app.glassray.ai/api/public/otel/v1/traces"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-api-key>"

Then create the exporter without a URL or headers, for example new OTLPTraceExporter() in Node.js or OTLPSpanExporter() in Python. You still need the rest of the setup code above.Want the same traces in another tool too? See Send traces to more than one tool.

Tag your traces

Tags go on two kinds of span:

The root span, one per run. It says who the run was for and what it was asked. glassray.agent is already set for the whole app by the setup code in the previous step.
A child span for each step, such as an LLM call. It says which model ran, how many tokens it used, and what went in and came out.

The example below handles a support ticket with one LLM call. It uses the Anthropic SDK, but the attribute names are the same for any provider. Every attribute is explained in a comment, and they’re all listed in What Glassray reads from your spans.

Node.js
Python
Ruby

import Anthropic from "@anthropic-ai/sdk";
import { trace } from "@opentelemetry/api";

type Ticket = { id: string; customerId: string; userId: string; conversationId: string; message: string };

const anthropic = new Anthropic();
const tracer = trace.getTracer("support-bot");

export const handleTicket = (ticket: Ticket) =>
  tracer.startActiveSpan(
    "handle-ticket",
    {
      attributes: {
        "glassray.customer": ticket.customerId, // which of your customers the run was for
        "glassray.flow": "refunds", // optional hint for which workflow this is
        "user.id": ticket.userId, // the end user the run served
        "session.id": ticket.conversationId, // groups the turns of one conversation
        ticket_id: ticket.id, // other root-span attributes become filters in Glassray
        "input.value": ticket.message, // what the run was asked
      },
    },
    async (root) => {
      try {
        const answer = await tracer.startActiveSpan("draft-reply", async (llm) => {
          try {
            const messages = [{ role: "user" as const, content: ticket.message }];
            llm.setAttributes({
              "gen_ai.operation.name": "chat", // marks this span as an LLM call
              "gen_ai.provider.name": "anthropic",
              "gen_ai.request.model": "claude-sonnet-4-6",
              "gen_ai.input.messages": JSON.stringify(messages), // the prompt
            });

            const response = await anthropic.messages.create({
              model: "claude-sonnet-4-6",
              max_tokens: 1024,
              messages,
            });
            const block = response.content[0];
            const text = block?.type === "text" ? block.text : "";

            llm.setAttributes({
              "gen_ai.response.model": response.model, // provider-reported model, used only if the request model is missing
              "gen_ai.usage.input_tokens": response.usage.input_tokens,
              "gen_ai.usage.output_tokens": response.usage.output_tokens,
              "gen_ai.output.messages": JSON.stringify([{ role: "assistant", content: text }]), // the response
            });
            return text;
          } finally {
            llm.end();
          }
        });

        root.setAttribute("output.value", answer); // what the run answered
        return answer;
      } finally {
        root.end();
      }
    },
  );

import json

from anthropic import Anthropic
from opentelemetry import trace

anthropic = Anthropic()
tracer = trace.get_tracer("support-bot")


def handle_ticket(ticket):
    with tracer.start_as_current_span(
        "handle-ticket",
        attributes={
            "glassray.customer": ticket["customer_id"],  # which of your customers the run was for
            "glassray.flow": "refunds",  # optional hint for which workflow this is
            "user.id": ticket["user_id"],  # the end user the run served
            "session.id": ticket["conversation_id"],  # groups the turns of one conversation
            "ticket_id": ticket["id"],  # other root-span attributes become filters in Glassray
            "input.value": ticket["message"],  # what the run was asked
        },
    ) as root:
        messages = [{"role": "user", "content": ticket["message"]}]

        with tracer.start_as_current_span(
            "draft-reply",
            attributes={
                "gen_ai.operation.name": "chat",  # marks this span as an LLM call
                "gen_ai.provider.name": "anthropic",
                "gen_ai.request.model": "claude-sonnet-4-6",
                "gen_ai.input.messages": json.dumps(messages),  # the prompt
            },
        ) as llm:
            response = anthropic.messages.create(
                model="claude-sonnet-4-6",
                max_tokens=1024,
                messages=messages,
            )
            answer = response.content[0].text

            llm.set_attributes({
                "gen_ai.response.model": response.model,  # provider-reported model, used only if the request model is missing
                "gen_ai.usage.input_tokens": response.usage.input_tokens,
                "gen_ai.usage.output_tokens": response.usage.output_tokens,
                "gen_ai.output.messages": json.dumps([{"role": "assistant", "content": answer}]),  # the response
            })

        root.set_attribute("output.value", answer)  # what the run answered
        return answer

require "json"
require "anthropic"

ANTHROPIC = Anthropic::Client.new
TRACER = OpenTelemetry.tracer_provider.tracer("support-bot")

def handle_ticket(ticket)
  TRACER.in_span("handle-ticket", attributes: {
    "glassray.customer" => ticket[:customer_id], # which of your customers the run was for
    "glassray.flow" => "refunds", # optional hint for which workflow this is
    "user.id" => ticket[:user_id], # the end user the run served
    "session.id" => ticket[:conversation_id], # groups the turns of one conversation
    "ticket_id" => ticket[:id], # other root-span attributes become filters in Glassray
    "input.value" => ticket[:message] # what the run was asked
  }) do |root|
    messages = [{ role: "user", content: ticket[:message] }]

    answer = TRACER.in_span("draft-reply", attributes: {
      "gen_ai.operation.name" => "chat", # marks this span as an LLM call
      "gen_ai.provider.name" => "anthropic",
      "gen_ai.request.model" => "claude-sonnet-4-6",
      "gen_ai.input.messages" => messages.to_json # the prompt
    }) do |llm|
      response = ANTHROPIC.messages.create(
        model: "claude-sonnet-4-6",
        max_tokens: 1024,
        messages: messages
      )
      text = response.content.first.text

      llm.add_attributes(
        "gen_ai.response.model" => response.model.to_s, # provider-reported model, used only if the request model is missing
        "gen_ai.usage.input_tokens" => response.usage.input_tokens,
        "gen_ai.usage.output_tokens" => response.usage.output_tokens,
        "gen_ai.output.messages" => [{ role: "assistant", content: text }].to_json # the response
      )
      text
    end

    root.set_attribute("output.value", answer) # what the run answered
    answer
  end
end

Nested spans don’t need a parent passed in. A span you start while another is active becomes its child, even if the code is in another function or file.For prompt-cache tokens, a cost you already know, or other providers’ token conventions, see Usage and cost attributes.

This step always needs code. Environment variables and a Collector only change where traces are sent. They can’t add tags that change per run, like glassray.customer, because only your app knows which customer a run is for.

GenAI instrumentation libraries such as OpenLIT, OpenLLMetry and OpenInference build on OTel and can add model and token attributes to your LLM spans. They don’t add Glassray’s tags. See What Glassray reads from your spans for the full list.

Check that traces arrive

Run your app so it creates at least one trace, then open Traces in Glassray. If nothing shows up, check your exporter’s logs for one of the error codes.

Endpoint reference

POST https://app.glassray.ai/api/public/otel/v1/traces
Authorization: Bearer <your-api-key>

Format: OTLP over HTTP, as protobuf (Content-Type: application/x-protobuf) or JSON (Content-Type: application/json). Most OTel SDKs send protobuf by default. Both work the same.
Compression: gzip (Content-Encoding: gzip) or none.
gRPC: not supported.
API key: must have the traces:write permission. Keys from an OpenTelemetry source have it.

What Glassray reads from your spans

Attribute	Set it on	What it’s for
`glassray.agent`	Resource	Which agent sent the trace
`glassray.customer` (or `glassray.customer.id`)	Root span	Which of your customers the run was for
`glassray.customer.name`, `glassray.customer.email`	Root span	Optional. The display name and a contact email for that customer, so Glassray shows a company and its logo instead of an identifier. The email is only used to work out the company domain (pass `glassray.customer.domain` if you have that instead) and is not stored. Fills only what nobody has set in Settings › Customers
`glassray.flow`	Root span	A hint for which flow the run belongs to
`user.id`	Root span	The end user the run served
`session.id`	Root span	Groups the turns of one conversation
`input.value`, `output.value`	Root span	What the run was asked and what it answered
`gen_ai.operation.name`	Each LLM span	Marks the span as an LLM call (for example `chat`)
`gen_ai.provider.name`	Each LLM span	The LLM provider (for example `anthropic`)
`gen_ai.request.model`	Each LLM span	The model, used for cost
`gen_ai.response.model`	Each LLM span	Used as the model only when `gen_ai.request.model` is missing
`gen_ai.usage.input_tokens`, `gen_ai.usage.output_tokens`	Each LLM span	Token counts, used to calculate cost
`gen_ai.input.messages`, `gen_ai.output.messages`	Each LLM span	The prompt and the response

Root-span attributes override resource attributes with the same name. Any other string, number or boolean attribute on the root span or the resource (such as report_id) becomes a filter in the Traces view. Attributes on child spans don’t, and neither do OTel namespaces such as service.* or http.*. Glassray keeps up to 48 of these per trace, with values up to 256 characters. For the full list, including prompt-cache tokens and cost, see Bring your own OTel.

How ingest behaves

Success

A 200 means the batch was received. The response uses the same Content-Type as the request.

Safe to retry

Sending the same spans again doesn’t create duplicates.

Batches are combined

Spans from the same trace sent in separate requests are merged into one trace. If your source has filters, see Limits.

Limits

Requests larger than 32 MB are rejected with 413.
A single trace larger than 16 MiB is skipped. The rest of the batch is still stored.
If your source has filters, traces that don’t match them aren’t stored. The request still returns 200.
Filters are checked on each request on its own. When an exporter sends a long run in several requests, a request that only has child spans is matched on a child span’s name. With a filter on the trace name, those child spans can be dropped before the root span arrives.

Error codes

Code	Meaning
`400`	The body isn’t valid OTLP for its `Content-Type` (malformed JSON or protobuf), or the gzip data is invalid.
`401`	The API key is missing or invalid.
`403`	The key lacks `traces:write`, the source is disabled, or ingestion is suspended for your organization.
`413`	The request is larger than 32 MB.
`415`	Unsupported `Content-Type` (use `application/json` or `application/x-protobuf`) or `Content-Encoding` (only `gzip`).
`503`	Ingestion is temporarily unavailable. Retry; resending the same spans is safe.

Send traces to more than one tool

If you want the same traces in Glassray and another tool, for example Langfuse, run an OTel Collector. It’s a separate service that receives traces from your apps and forwards them to several tools at once.

otel-collector-config.yaml

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  otlphttp/glassray:
    traces_endpoint: https://app.glassray.ai/api/public/otel/v1/traces
    headers:
      Authorization: "Bearer ${env:GLASSRAY_API_KEY}"
  otlphttp/other-tool: # for example Langfuse
    traces_endpoint: https://otel.other-tool.example/v1/traces # the OTLP traces URL from that tool's docs
    headers:
      Authorization: "Bearer ${env:OTHER_TOOL_API_KEY}" # the auth header from that tool's docs

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/glassray, otlphttp/other-tool]

Point your app’s exporter at the Collector instead of Glassray, for example http://localhost:4318/v1/traces, with no API key. The Collector adds each tool’s key when it forwards traces. Use the otlphttp exporter, not the gRPC otlp exporter: Glassray only accepts HTTP.

Get started

Glassray CLI

Coach (local)

Concepts

Trace sources

Glassray SDK

Integrations

Explore

Send traces with OpenTelemetry (OTLP)

Setup

Endpoint reference

What Glassray reads from your spans

How ingest behaves

Success

Safe to retry

Batches are combined

Limits

Error codes

Send traces to more than one tool

​Setup

​Endpoint reference

​What Glassray reads from your spans

​How ingest behaves

Success

Safe to retry

Batches are combined

​Limits

​Error codes

​Send traces to more than one tool

Setup

Endpoint reference

What Glassray reads from your spans

How ingest behaves

Limits

Error codes

Send traces to more than one tool