OpenTelemetry

Use this path when your application already emits OpenTelemetry (OTEL) spans, you use an OpenTelemetry Collector, or no dedicated PromptLayer integration supports your library. You do not need a PromptLayer SDK. Exported spans appear in Traces. For a supported model provider SDK or framework, use its dedicated SDK Auto-Instrumentation or Telemetry Integration instead. The Tracing overview compares all tracing paths.

OTLP Endpoint

PromptLayer exposes an OTLP/HTTP endpoint at:

https://api.promptlayer.com/v1/traces

Any OpenTelemetry SDK or Collector can export traces to this endpoint. Spans that include GenAI semantic convention attributes are automatically converted into PromptLayer request logs.

Configure an SDK

Configure your OpenTelemetry SDK to export traces to PromptLayer using the OTLP/HTTP exporter.

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

# Install required packages:
# pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

exporter = OTLPSpanExporter(
    endpoint="https://api.promptlayer.com/v1/traces",
    headers={"X-API-KEY": "your-promptlayer-api-key"},
)

provider = TracerProvider(
    resource=Resource.create({"service.name": "my-llm-app"})
)
provider.add_span_processor(BatchSpanProcessor(exporter))

# Use the tracer to create spans
tracer = provider.get_tracer("my-llm-app")

// Install required packages:
// npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources

import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { resourceFromAttributes } from "@opentelemetry/resources";

const sdk = new NodeSDK({
  serviceName: "my-llm-app",
  resource: resourceFromAttributes({
    "service.name": "my-llm-app",
  }),
  traceExporter: new OTLPTraceExporter({
    url: "https://api.promptlayer.com/v1/traces",
    headers: {
      "X-API-Key": process.env.PROMPTLAYER_API_KEY,
    },
  }),
});

sdk.start();

// Shut down before exit to flush remaining spans
process.on("beforeExit", async () => {
  await sdk.shutdown();
});

GenAI Semantic Conventions

Spans that use GenAI semantic conventions are automatically parsed into PromptLayer request logs. Add these attributes to your LLM call spans:

Attribute	Description
`gen_ai.request.model`	Model name (e.g. `gpt-4`, `claude-sonnet-4-20250514`)
`gen_ai.provider.name`	Provider (e.g. `openai`, `anthropic`)
`gen_ai.operation.name`	Operation type (`chat`, `text_completion`, `embeddings`)
`gen_ai.usage.input_tokens`	Input token count
`gen_ai.usage.output_tokens`	Output token count
`gen_ai.input.messages`	Request messages
`gen_ai.output.messages`	Response messages
`gen_ai.request.temperature`	Temperature parameter
`gen_ai.request.max_tokens`	Max tokens parameter
`gen_ai.response.finish_reasons`	Finish reasons

Event-Based Conventions

PromptLayer also supports the newer event-based GenAI semantic conventions where message content is sent as span events rather than span attributes. This format is used by frameworks like LiveKit and newer versions of OpenTelemetry GenAI instrumentation. The following event types are recognized:

Event Name	Description
`gen_ai.system.message`	System message
`gen_ai.user.message`	User message
`gen_ai.assistant.message`	Assistant message (including tool calls)
`gen_ai.tool.message`	Tool/function result message
`gen_ai.choice`	Model response/choice

Event attributes like gen_ai.system.message.content, gen_ai.user.message.content, and tool call data are automatically extracted and mapped to PromptLayer request logs.

When both attribute-based messages (gen_ai.input.messages) and event-based messages are present on the same span, attribute-based messages take priority.

Linking to Prompt Templates

You can associate OTEL spans with prompt templates in your PromptLayer workspace by setting custom span attributes:

Attribute	Type	Description
`promptlayer.prompt.name`	string	Name of the prompt template in your workspace
`promptlayer.prompt.version`	integer	Specific version number to link (optional)

from opentelemetry import trace

tracer = trace.get_tracer("my-llm-app")

with tracer.start_as_current_span("llm-call") as span:
    # Link this span to a prompt template
    span.set_attribute("promptlayer.prompt.name", "my-prompt")
    span.set_attribute("promptlayer.prompt.version", 3)

    # Add GenAI attributes
    span.set_attribute("gen_ai.request.model", "gpt-4")
    span.set_attribute("gen_ai.provider.name", "openai")

    # ... make your LLM call ...

import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("my-llm-app");

tracer.startActiveSpan("llm-call", (span) => {
  // Link this span to a prompt template
  span.setAttribute("promptlayer.prompt.name", "my-prompt");
  span.setAttribute("promptlayer.prompt.version", 3);

  // Add GenAI attributes
  span.setAttribute("gen_ai.request.model", "gpt-4");
  span.setAttribute("gen_ai.provider.name", "openai");

  // ... make your LLM call ...

  span.end();
});

Attaching User Identity & Metadata

You can attach searchable metadata — including end-user identity and conversation IDs — to the request logs generated from your spans. This is the OpenTelemetry-native equivalent of the PromptLayer SDK’s track.metadata(), with no extra REST call required. PromptLayer recognizes two kinds of span attributes for metadata.

Standard OpenTelemetry attributes

If your instrumentation already follows OpenTelemetry conventions, these are picked up automatically — no PromptLayer-specific attributes needed:

Attribute	Mapped to	Description
`user.id`	`user_id` metadata	End-user identity (current OpenTelemetry attribute)
`enduser.id`	`user_id` metadata	End-user identity (deprecated OpenTelemetry attribute, supported as a fallback)
`gen_ai.conversation.id`	`conversation_id` metadata	Conversation / session / thread identifier (OpenTelemetry GenAI attribute)
`session.id`	`conversation_id` metadata	Conversation identifier (common alias, supported as a fallback)

PromptLayer custom metadata

For arbitrary key/value metadata, use the promptlayer.metadata. namespace. Each attribute becomes a metadata key on the request log — for example, promptlayer.metadata.tenant becomes a tenant metadata key.

Attribute	Mapped to
`promptlayer.metadata.<key>`	`<key>` metadata

with tracer.start_as_current_span("llm-call") as span:
    # Standard OpenTelemetry attributes
    span.set_attribute("user.id", "customer-42")
    span.set_attribute("gen_ai.conversation.id", "conv_abc123")

    # Arbitrary PromptLayer metadata
    span.set_attribute("promptlayer.metadata.tenant", "acme-corp")
    span.set_attribute("promptlayer.metadata.environment", "production")

    # ... make your LLM call ...

tracer.startActiveSpan("llm-call", (span) => {
  // Standard OpenTelemetry attributes
  span.setAttribute("user.id", "customer-42");
  span.setAttribute("gen_ai.conversation.id", "conv_abc123");

  // Arbitrary PromptLayer metadata
  span.setAttribute("promptlayer.metadata.tenant", "acme-corp");
  span.setAttribute("promptlayer.metadata.environment", "production");

  // ... make your LLM call ...

  span.end();
});

An explicit promptlayer.metadata.<key> always takes precedence over a standard attribute mapped to the same key. For example, if a span has both user.id and promptlayer.metadata.user_id, the promptlayer.metadata.user_id value wins.

Metadata is attached to the request log generated from the span, so set these attributes on your LLM call spans. To apply metadata across an entire trace, set the attributes as resource attributes — they apply to every span in the export.

Using an OpenTelemetry Collector

If you’re already running an OpenTelemetry Collector, you can add PromptLayer as an additional exporter in your Collector config:

exporters:
  otlphttp/promptlayer:
    endpoint: "https://api.promptlayer.com"
    headers:
      X-API-Key: "${PROMPTLAYER_API_KEY}"

service:
  pipelines:
    traces:
      exporters: [otlphttp/promptlayer]

This lets you fan out traces to PromptLayer alongside your existing observability backends (Datadog, New Relic, Jaeger, etc.) without changing your application code.

API Reference

See Ingest Traces (OTLP) for authentication, accepted encodings, compression, request schemas, responses, and errors.

Get Started

Core Concepts

Providers

Guides

AI Tools

Reference

Deprecated

OTLP Endpoint

Configure an SDK

GenAI Semantic Conventions

Event-Based Conventions

Linking to Prompt Templates

Attaching User Identity & Metadata

Standard OpenTelemetry attributes

PromptLayer custom metadata

Using an OpenTelemetry Collector

API Reference

​OTLP Endpoint

​Configure an SDK

​GenAI Semantic Conventions

​Event-Based Conventions

​Linking to Prompt Templates

​Attaching User Identity & Metadata

​Standard OpenTelemetry attributes

​PromptLayer custom metadata

​Using an OpenTelemetry Collector

​API Reference

OTLP Endpoint

Configure an SDK

GenAI Semantic Conventions

Event-Based Conventions

Linking to Prompt Templates

Attaching User Identity & Metadata

Standard OpenTelemetry attributes

PromptLayer custom metadata

Using an OpenTelemetry Collector

API Reference