Traces

Traces are a powerful feature in PromptLayer that allow you to monitor and analyze the execution flow of your applications, including LLM requests. Built on OpenTelemetry, Traces provide detailed insights into function calls, their durations, inputs, and outputs.

This page covers tracing with the PromptLayer SDK (@traceable, wrapWithSpan). If you want to send traces from any OpenTelemetry SDK or Collector without using the PromptLayer SDK, see the OpenTelemetry page. For framework-specific integrations (Vercel AI SDK, OpenAI Agents, Claude Code), see Telemetry Integrations.

Overview

Traces in PromptLayer offer a comprehensive view of your application’s performance and behavior. They allow you to:

Visualize the execution flow of your functions
Track LLM requests and their associated metadata
Measure function durations and identify performance bottlenecks
Inspect function inputs and outputs for debugging

Note: The left menu in the PromptLayer UI only shows root spans, which represent the entry function of your program. While your program is running, you might not see all spans in the UI immediately, even though child spans are being sent to the backend. The root span, along with all its child spans, will only appear in the UI once the program completes. This behavior is particularly noticeable in long-running programs or those with complex execution flows.

Automatic LLM Request Tracing

When you initialize the PromptLayer class with enable_tracing set to True, PromptLayer will automatically track any LLM calls made using the PromptLayer library. This allows you to capture detailed information about your LLM requests, including:

Model used
Input prompts
Generated responses
Request duration
Associated metadata

from promptlayer import PromptLayer

# Initialize PromptLayer with tracing enabled
pl_client = PromptLayer(enable_tracing=True)

import { PromptLayer } from "promptlayer";

// Initialize PromptLayer with tracing enabled
const promptlayer = new PromptLayer({
    apiKey: process.env.PROMPTLAYER_API_KEY,
    enableTracing: true,
});

Once PromptLayer is initialized with tracing enabled, you can use the run() method to execute prompts. All LLM calls made through this method will be automatically traced, providing detailed insights into your prompt executions.

response = pl_client.run(
    prompt_name="simple-greeting",
    input_variables={
        "name": "Alice"
    },
    metadata={
        "user_id": "12345"
    }
)

print(response)

async function runPrompt() {
    try {
        const response = await promptlayer.run({
            promptName: "simple-greeting",
            inputVariables: {
                name: "Alice"
            },
            metadata: {
                user_id: "12345"
            }
        });

        console.log(response);
    } catch (error) {
        console.error("Error running prompt:", error);
    }
}

runPrompt();

Custom Function Tracing

In addition to automatic LLM request tracing, you can also use the traceable decorator (for Python) or wrapWithSpan (for JavaScript) to explicitly track span data for additional functions. This allows you to gather detailed information about function executions.

# Use the @pl_client.traceable() decorator to trace a function
@pl_client.traceable()
def greet(name):
    return f"Hello, {name}!"

# Use the decorator with custom attributes
@pl_client.traceable(attributes={"function_type": "math"})
def calculate_sum(a, b):
    return a + b

result1 = greet("Alice")
print(result1)

result2 = calculate_sum(5, 3)
print(result2)

// Define and wrap a function with PromptLayer tracing
const greet = promptlayer.wrapWithSpan('greet', (name: string): string => {
    return `Hello, ${name}!`;
});

const result = greet("Alice");
console.log(result);

Setting Custom Span Names

When tracing functions, you may want to set custom names for your spans to make them more descriptive. Both Python and JavaScript implementations of PromptLayer allow you to set custom span names.

Python

In Python, you can set a custom span name by passing the name parameter to the traceable decorator:

@pl_client.traceable(name="CustomGreeting")
def greet(name):
    return f"Hello, {name}!"

result = greet("Alice")
print(result)

If you don’t provide a name parameter, the span will use the function’s name by default.

JavaScript

In JavaScript, you can set a custom span name by passing it as the first argument to the wrapWithSpan function:

JavaScript

const greet = promptlayer.wrapWithSpan('CustomGreeting', (name) => {
    return `Hello, ${name}!`;
});

const result = greet("Alice");
console.log(result);

If you want to use the function’s name as the span name, you can simply pass the function name as a string:

JavaScript

const greet = promptlayer.wrapWithSpan('greet', (name) => {
    return `Hello, ${name}!`;
});

Creating Parent Spans and Grouping Function Calls

To create a parent span and group multiple function calls within it, you can use the traceable decorator on a main function that calls other traced functions. Here’s an example that demonstrates this concept:

from promptlayer import PromptLayer

# Initialize PromptLayer with tracing enabled
pl_client = PromptLayer(enable_tracing=True)

@pl_client.traceable(name="custom-span")
def main():
    # This function will be the parent span
    openai_call()
    anthropic_call()
    custom_function()
    run_prompt()

@pl_client.traceable()
def openai_call():
    response = pl_client.run(
        prompt_name="simple-greeting",
        input_variables={}
    )
    print("OpenAI response:", response["prompt_blueprint"]["prompt_template"]["messages"][-1])

@pl_client.traceable()
def anthropic_call():
    response = pl_client.run(
        prompt_name="simple-greeting",
        input_variables={},
        provider="anthropic",
        model="claude-sonnet-4-20250514"
    )
    print("Anthropic response:", response["prompt_blueprint"]["prompt_template"]["messages"][-1])

@pl_client.traceable()
def custom_function():
    # This is a custom function that will be traced
    result = "Custom function executed"
    print(result)
    return result

@pl_client.traceable()
def run_prompt():
    response = pl_client.run(
        prompt_name="simple-greeting",
        input_variables={}
    )
    print("Prompt response:", response["prompt_blueprint"]["prompt_template"]["messages"][-1])

if __name__ == "__main__":
    main()

Filtering Traces by Span Attributes

The trace list can be filtered by metadata and resource attribute values. Filters search across the entire span hierarchy — a trace appears in results if any span within it (root or child) carries a matching attribute. For example, if only a nested LLM call span has {"environment": "production"} in its attributes, filtering the trace list by environment = production will still surface the parent trace in results, even if the root span itself does not carry that attribute.

Adding Filters from the Span Detail Panel

When you open a span in the trace detail view, hovering over a scalar metadata or resource value reveals a filter button. Clicking it adds the key-value pair as an active filter on the trace list. The filter button appears only for top-level scalar values (string, number, or boolean). Nested objects and arrays are displayed for inspection but cannot be used as direct filter targets.

Trace Analytics

Custom analytics charts can aggregate over traces at two levels: whole traces or the individual spans inside them. Charts are available from the analytics dashboard, through the PromptLayer AI assistant (e.g. “show me the slowest tools across my agent-turn traces this week”), and via the public API — see Trace Analytics — Custom Queries.

Trace-level charts

Group and measure whole traces. Group-by fields: trace_status, trace_name, trace_models_used, trace_prompt_ids, trace_workflow_ids, trace_tool_names. Metric fields: trace_duration_ms, trace_total_cost_usd, trace_total_tokens, trace_input_tokens, trace_output_tokens, trace_span_count, trace_depth.

Span-level charts

Group and measure the individual spans inside matching traces — trace-level filters (like trace_name or a time range) select which traces participate, then the aggregation runs across every span within them.

Group-by fields: span_tool_name, span_name, span_type, span_kind, span_status
Metric fields: span_duration_ms, span_cost_usd, span_tokens, span_input_tokens, span_output_tokens

All standard metrics apply (count, sum, avg, min, max, percentile). Span durations are returned in seconds. Example questions this answers:

Which tool has the highest max/p95 latency across my agent traces? (groupByField: span_tool_name, metric: max, metricField: span_duration_ms)
How many times was each tool called? (groupByField: span_tool_name, metric: count)
What’s the distribution of span durations? (chartType: histogram, histogramField: span_duration_ms)
Which span types account for the most cost? (groupByField: span_type, metric: sum, metricField: span_cost_usd)

A chart must stay at one level: span-level fields cannot be mixed with trace-level fields in the same chart, and span-level charts do not support timeSeries or metadata-key breakdowns.

Get Started

Core Concepts

Providers

Guides

AI Tools

Reference

Deprecated

Overview

Automatic LLM Request Tracing

Custom Function Tracing

Setting Custom Span Names

Python

JavaScript

Creating Parent Spans and Grouping Function Calls

Filtering Traces by Span Attributes

Adding Filters from the Span Detail Panel

Trace Analytics

Trace-level charts

Span-level charts

​Overview

​Automatic LLM Request Tracing

​Custom Function Tracing

​Setting Custom Span Names

​Python

​JavaScript

​Creating Parent Spans and Grouping Function Calls

​Filtering Traces by Span Attributes

​Adding Filters from the Span Detail Panel

​Trace Analytics

​Trace-level charts

​Span-level charts

Overview

Automatic LLM Request Tracing

Custom Function Tracing

Setting Custom Span Names

Python

JavaScript

Creating Parent Spans and Grouping Function Calls

Filtering Traces by Span Attributes

Adding Filters from the Span Detail Panel

Trace Analytics

Trace-level charts

Span-level charts