How to Use Traceloop: Instrument Your First LLM App (OpenTelemetry Traces, Workflows, and the Dashboard)

CodexFuse Team · 2026-11-06T13:14:31.793Z · 20 min read min read

How to Use Traceloop: Instrument Your First LLM App (OpenTelemetry Traces, Workflows, and the Dashboard)

Learning how to use Traceloop takes about fifteen minutes if you follow the official Python quickstart instead of a third-party integration guide. Traceloop is an LLM observability platform that records every call your app makes to a language model as a trace you can inspect, so you can see prompts, token use, latency, and errors instead of guessing why an answer went wrong.

To use Traceloop, install the traceloop-sdk package, call Traceloop.init() before your first LLM call, and open the dashboard to see your first trace. The rest of this traceloop tutorial follows that arc exactly, from install to your first decorated workflow to exporting traces to your own backend.

All facts in this guide are as of November 2026, and version numbers move fast, so treat the release details as a snapshot. This guide is about Traceloop, the LLM observability platform, not the unrelated Inspektor Gadget eBPF syscall recorder that shares the name. CodexFuse offers no Traceloop tool, so this guide teaches the open-source SDK and the Traceloop dashboard itself, step by step, with every version and code sample taken from the official docs and the project repository.

What Is Traceloop?

Traceloop is an LLM observability platform that shows you what your language-model app actually did on every request. When your app calls a model, Traceloop records that call as a span, and a full request becomes a trace made of spans, so you can follow a user question from your code through the model call and back.

Every call to an LLM, and every call to a vector database, counts as a span, according to the definition on Traceloop's own pricing page. That matters because a single user question can trigger a chain: a vector search, several model calls, and a tool call, and without traces you only see the final answer. With traces, you see each step, how long it took, and what it cost in tokens.

Traceloop is built for developers whose LLM apps have moved past the demo stage. A prototype that answers one question at a time does not need observability, but a production app serving real users does, because prompts drift, models change behavior, and a slow retrieval step can quietly double your latency. If you already build with LangChain, our LangChain beginner guide covers the framework Traceloop most often instruments, and the rest of this guide assumes you have a small LLM app to point it at.

The platform has two halves. OpenLLMetry is the open-source instrumentation layer, and Traceloop Cloud is the hosted dashboard where the traces land. You can use the first half without the second, which is the subject of the export section later in this guide.

How Does Traceloop Work Under the Hood?

Traceloop is an LLM observability OpenTelemetry product: it records what your LLM app does as OpenTelemetry traces, using the OpenLLMetry standard. OpenLLMetry is a set of extensions built on top of OpenTelemetry that gives you complete observability over your LLM application, and it is built and maintained by Traceloop under the Apache 2.0 license.

The mental model has three layers. At the bottom sits OpenTelemetry, the vendor-neutral standard for traces, metrics, and logs.

In the middle sits OpenLLMetry, which adds LLM-specific semantic conventions, so a span knows it is a chat completion with a model name, a prompt, and a token count, rather than a generic HTTP call. At the top sits the Traceloop SDK, which auto-instruments your code, so you do not wrap every call by hand.

Auto-instrumentation is the feature that makes the first five minutes feel easy. If you use a supported framework, no annotation is needed, because OpenLLMetry automatically detects the framework and annotates your traces.

The instrumented providers include OpenAI, Anthropic, Google Gemini, Groq, Mistral AI, Together AI, and Ollama, and the instrumented frameworks include LangChain, LangGraph, LlamaIndex, Haystack, CrewAI, and LiteLLM, plus the MCP protocol. If you run models locally, our Ollama beginner guide covers the local model server that OpenLLMetry can trace the same way it traces a hosted API.

Because the data is standard OpenTelemetry, the dashboard is a choice, not a lock-in. The SDK emits spans in the OTel format, and you can point them at Traceloop Cloud or at any of the 25-plus supported observability platforms, including Datadog, Honeycomb, New Relic, Grafana Tempo, and SigNoz. The export section of this guide shows the two environment variables that make that switch.

What Do You Need Before You Start?

You need four things before your first trace, and none of them takes long. A Python environment, the SDK, an API key for your language model, and a Traceloop account with its own API key. The table below lists each prerequisite and where it comes from.

The API key step has one quirk worth knowing before you start. You generate the key in the dashboard by selecting a project and an environment, then clicking Generate API key, and the key is shown only once, so copy it immediately. If you lose it, you generate a new one rather than recovering the old one.

The free tier is generous enough for a first project. The Free Forever plan costs 0 dollars per month and covers up to 50,000 spans per month with 24 hours of data retention, according to the official pricing page. That works out to about 1,666 spans a day, which is far more than a learning project sends.

How Do You Install Traceloop?

Installing the traceloop sdk takes one command, and the whole first-trace arc takes seven steps. The list below is the complete arc, and the sections after it explain each step in detail.

1. Install the SDK with pip install traceloop-sdk.
2. Create a free Traceloop account and generate an API key in Settings.
3. Export the key as the TRACELOOP_API_KEY environment variable.
4. Import Traceloop and call Traceloop.init() before your first LLM call.
5. Run your app and make at least one LLM call.
6. Open the Traceloop dashboard and find your first trace.
7. Decorate your functions with @workflow and @task so traces stay readable as your app grows.

The install command comes straight from the official Python quickstart, and the minimal init is two lines of code. For local runs, pass disable_batch=True so traces appear immediately instead of waiting for the SDK's batch timer.

pip install traceloop-sdk

from traceloop.sdk import Traceloop
Traceloop.init(disable_batch=True)

Version 0.63.0 is the current release, published on 5 November 2026, which is 1 day before this guide was written. That freshness matters because the SDK moves quickly: version 0.62.4 shipped on 29 September 2026, and 37 days passed before 0.63.0 arrived with its headline change, a new trace_content parameter on Traceloop.init(). Pin the version in your requirements file once you ship, so a new release never changes your instrumentation without you noticing.

How Do You Initialize Traceloop?

Initialization is one call, and its placement is the single most important detail in this guide. Call Traceloop.init() before your app makes its first LLM call or creates its first agent, because instrumentation hooks into the libraries at that point, and calls made before init are invisible to the dashboard.

The traceloop init call accepts an app name, which labels every trace your app sends. If you pass nothing, it defaults to your script's file name, so pass an explicit name like app_name="joke_generation_service" to keep the dashboard readable. The Agno framework docs put it plainly: initialize Traceloop before creating any agents to ensure proper instrumentation.

from traceloop.sdk import Traceloop

Traceloop.init(app_name="my_first_llm_app", disable_batch=True)

There is a common trap here, and it comes from a half-remembered rule. In Python, there is no import-order requirement: you do not need to import Traceloop before your LLM libraries.

The import-before-LLM-libraries rule is TypeScript and JavaScript only, according to the official troubleshooting page, which labels it "(TS/JS only)". Third-party Python guides import openai before calling Traceloop.init(), and that works fine, because what matters in Python is the order of the init call relative to your LLM calls, not the order of your import lines.

Two init options deserve a line each. The disable_batch=True option sends each span immediately, which is what you want while learning, and the trace_content parameter, new in version 0.63.0, controls whether prompt and completion text is recorded in spans. If your app handles sensitive user input, set trace_content to False, or export TRACELOOP_TRACE_CONTENT=false, so prompts and completions never leave your machine.

How Do You See Your First Trace in the Dashboard?

Run your instrumented app once, then open the Traceloop dashboard, and your trace should be waiting. The official quickstart promises instant visibility into everything happening with your LLM, and when you run instrumented code, you get a link to the Traceloop UI where you can see your app's traces. The dashboard itself sits behind a login, so this guide follows the docs rather than narrating clicks it could not verify hands-on.

A trace reads like a timeline. The top span is your workflow, nested below it are the steps your code took, and each LLM call shows its model, its token counts, and its latency. Vector-database calls appear in the same trace, so a retrieval-augmented app shows its search step next to its generation step, which is exactly the view you need when an answer is slow or wrong.

If nothing appears, check two things before anything else. First, confirm you are viewing the correct project and environment in the dashboard, because traces land under the project and environment your API key belongs to. Second, remember that the SDK batches spans by default, so either wait 10 to 30 seconds after your calls, as the SigNoz guide advises, or restart with disable_batch=True and watch the trace arrive immediately.

How Do Traceloop Workflow and Task Decorators Work?

Traceloop workflow task decorators are the @workflow and @task annotations that turn a flat list of spans into a readable story. Automatic instrumentation already records every LLM call, but it cannot know which calls belong to the same business step, so you mark the boundaries yourself with decorators.

The decorators take an optional name, and without it the function name is used. Workflows and tasks can also be versioned, for example @workflow(name="my_workflow", version=2), so you can compare the behavior of a new prompt against the old one in the same dashboard. Decorators work with both sync and async functions in Python, and classes can be decorated too.

from traceloop.sdk.decorators import workflow, task

@workflow(name="suggest_answers")
def suggest_answers(question: str):
    draft = create_draft(question)
    return polish_draft(draft)

@task(name="create_draft")
def create_draft(question: str):
    return "draft answer for: " + question

One naming detail saves a future headache. The async-specific decorators @aworkflow and @atask are deprecated and will be removed in a future version, so use @workflow and @task for sync and async alike. If you copy a decorator example from an older tutorial and it uses @aworkflow, update it before you paste.

Decorators are optional where auto-instrumentation already covers you. If you use a supported LLM framework, no annotation is needed, because OpenLLMetry automatically detects the framework and annotates your traces. Add @workflow and @task where the automatic spans do not show the business boundary, such as the point where a user request turns into a multi-step job.

How Do You Trace Agents and Tools?

Agent apps need two more decorators: mark the agent entry point with @agent and each tool it can call with @tool. The dashboard then shows the agent as one unit with its tools nested underneath, so a run that calls three tools and two models still reads as a single story instead of a pile of spans.

from traceloop.sdk.decorators import agent, tool
from openai import OpenAI

client = OpenAI()

@agent(name="joke_translator")
def translate_joke(joke: str):
    history_jokes_tool()
    completion = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": "Translate this joke to pirate English: " + joke}],
    )
    return completion.choices[0].message.content

@tool(name="history_jokes")
def history_jokes_tool():
    completion = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": "Tell me a short history joke"}],
    )
    return completion.choices[0].message.content

The pattern is the same one the official annotations docs teach: the agent function does the reasoning, and every tool call inside it becomes a child span. OpenLLMetry also instruments the MCP protocol, so tool calls made through MCP appear in traces without extra code, and if you want the background on that protocol, our what MCP is explainer covers it in plain English.

How Do You Send Traces to Your Own Backend?

Traceloop Cloud is the default destination, but it is not the only one, because the SDK emits standard OpenTelemetry data. Two environment variables control where traces go, and changing them is all it takes to send the same spans to a different platform.

The base URL has one rule worth memorizing. If it starts with http or https, the SDK uses OTLP over HTTP, and otherwise it uses OTLP over gRPC, and the SDK appends /v1/traces to whatever you set. The TRACELOOP_HEADERS variable is sent as-is as HTTP headers, in key=value pairs separated by commas, for platforms that need custom authentication.

The same export path powers the hallucination-monitoring setup that Traceloop's own blog teaches. Its LangChain RAG article shows how to turn on the built-in Faithfulness and QA Relevancy monitors in the dashboard, import Traceloop's ready-made Grafana dashboards from the openllmetry repository, and alert when more than 5 percent of spans are flagged in five minutes.

If you want that alerting layer, our Grafana beginner guide covers the dashboard tool those JSON files are built for. Treat that article as a next step, not as the how-to itself, because it assumes you already have a working RAG pipeline and focuses on adding monitoring in production.

Should You Self-Host Traceloop or Use the Cloud?

The cloud dashboard is the right start for almost everyone, and self-hosting is the right answer for a smaller group with strict requirements. The table below compares the two paths on the points that actually decide the choice.

Full-platform self-hosting is documented, with two shapes: Terraform or CloudFormation for the managed infrastructure plus Helm for the apps, which the docs recommend for production, or an all-in-one Helm deployment for development and testing. The self-host compatibility matrix lists the core services at version 0.3.0, dated May 2025, with quarterly releases. If you go this route, our Docker beginner guide covers the container skills the deployment assumes, though the production path is Kubernetes rather than plain Docker.

There is also a middle path that many teams choose first. Keep the SDK, point TRACELOOP_BASE_URL at your own OpenTelemetry Collector or an existing observability platform, and skip running the Traceloop platform entirely. You lose the Traceloop-specific dashboards, but your traces land in the system your team already watches, and you can switch to Traceloop Cloud later without changing a line of application code.

How Much Does Traceloop Cost, and Who Owns It Now?

Traceloop costs nothing to start with. The Free Forever plan is 0 dollars per month, covers up to 50,000 spans per month, and keeps data for 24 hours, and it includes the monitoring dashboard, the evaluation dashboard, prompt management, and CI/CD integration. The Enterprise tier is priced by conversation and adds unlimited spans, custom retention, SOC 2 compliance, on-premises deployment, and dedicated Slack support.

One detail on the pricing page deserves a careful reading. The Free Forever card says up to 5 seats, while the FAQ on the same page says there is no seat limit and all features are open, so the page contradicts itself on seats. This guide cites only the 50,000-span figure as settled, because that number appears on both the plan card and the FAQ.

The ownership picture changed in 2026. ServiceNow acquired Traceloop, with the deal announced in early March 2026, which is 249 days before this guide was written, and the pricing page now carries a banner that reads "Traceloop is joining ServiceNow!".

The price was never officially disclosed; Calcalist estimated 60 to 80 million dollars, and PitchBook lists 70 million dollars. The product has not been renamed: the SDK, the docs, and the GitHub repository are still branded Traceloop and OpenLLMetry as of 6 November 2026.

The acquisition makes more sense with the funding history beside it. Traceloop raised a 6.1 million dollar seed round in May 2025, which is 528 days before this guide was written, from investors including Sorenson Capital, Ibex Investors, Samsung NEXT, Y Combinator, and Grand Ventures. ServiceNow plans to fold Traceloop into its AI Control Tower, which is why the acquisition matters to users: the dashboard you learn today is likely to become part of a larger enterprise AI platform, while the open-source OpenLLMetry layer stays Apache 2.0 and independent of any one vendor.

from datetime import date
today = date(2026, 11, 6)
print("days since v0.63.0 release (2026-11-05):", (today - date(2026, 11, 5)).days)
print("days since repo creation (2023-09-02):", (today - date(2023, 9, 2)).days)
print("repo age in years:", round((today - date(2023, 9, 2)).days / 365.25, 2))
print("days since ServiceNow acquisition (2026-03-02):", (today - date(2026, 3, 2)).days)
print("days since seed round (2025-05-27):", (today - date(2025, 5, 27)).days)
print("stars per fork (7523/1187):", round(7523 / 1187, 2))
print("stars per release (7523/264):", round(7523 / 264, 1))
print("free-tier spans per day (50000/30):", round(50000 / 30, 1))
print("days v0.62.4 to v0.63.0:", (date(2026, 11, 5) - date(2026, 9, 29)).days)

The numbers above come from a Python script run while writing this guide. Version 0.63.0 is 1 day old, the repository is 1,161 days old, or 3.18 years, and the acquisition was announced 249 days ago.

The seed round closed 528 days ago. The repository's 7,523 stars against 1,187 forks work out to 6.34 stars per fork, and 28.5 stars per release across 264 releases. The free tier's 50,000 spans a month allow about 1,666.7 spans a day, and 37 days passed between version 0.62.4 and version 0.63.0.

What Mistakes Should You Avoid?

Most Traceloop setups fail in one of six ways, and all six are avoidable. The first is the import-order myth: reordering your Python imports to put Traceloop first, which the docs never ask for, while forgetting to call init before your first LLM call, which they do. The second is pinning a stale version from an old guide, such as the 0.41.0 pin in IBM's Instana docs, when the current release is 0.63.0.

The third is using the deprecated @aworkflow decorator from an older tutorial instead of @workflow. The fourth is forgetting disable_batch=True during local development and concluding the SDK is broken when traces simply have not flushed yet. The fifth is looking at the wrong project or environment in the dashboard, which shows an empty screen even when your app is sending traces correctly.

The sixth is a privacy mistake rather than a setup mistake. By default, Traceloop records prompt and completion text inside spans, which means user messages travel to whichever backend you chose. If your app handles personal or sensitive input, turn content capture off with trace_content=False on init or TRACELOOP_TRACE_CONTENT=false in the environment before you send your first real user request, not after.

Sources

Official Traceloop Python quickstart (traceloop.com/docs/openllmetry/getting-started-python). Official Traceloop TypeScript quickstart (traceloop.com/docs/openllmetry/getting-started-ts). Official Traceloop troubleshooting page (traceloop.com/docs/openllmetry/troubleshooting).

Official Traceloop annotations reference (traceloop.com/docs/openllmetry/tracing/annotations). Official Traceloop configuration reference (traceloop.com/docs/openllmetry/configuration). Official Traceloop integrations catalogue (traceloop.com/docs/openllmetry/integrations/introduction).

Official Traceloop Oracle Cloud integration (traceloop.com/docs/openllmetry/integrations/oraclecloud). Official Traceloop self-hosting guide (traceloop.com/docs/self-host/full-deployment). Official Traceloop pricing page (traceloop.com/pricing).

Traceloop openllmetry GitHub repository and releases (github.com/traceloop/openllmetry). PyPI traceloop-sdk 0.63.0 page (pypi.org/project/traceloop-sdk/). Traceloop blog: Tools to Detect and Reduce Hallucinations in a LangChain RAG Pipeline in Production (traceloop.com/blog/tools-to-detect-reduce-hallucinations-in-a-langchain-rag-pipeline-in-production).

Traceloop blog: Beyond Spreadsheets, Building a Scalable Framework for Evaluating Faithfulness and Relevance in LLMs (traceloop.com/blog/beyond-spreadsheets-building-a-scalable-framework-for-evaluating-faithfulness-relevance-in-llms). Traceloop blog: The Specialized LLM Observability Platform Built on OpenTelemetry (traceloop.com/blog/the-specialized-llm-observability-platform-built-on-opentelemetry-traceloop). Agno Traceloop observability docs (docs.agno.com/observability/traceloop).

Haystack Traceloop integration (haystack.deepset.ai/integrations/traceloop). SigNoz Traceloop observability guide (signoz.io/docs/traceloop/). New Relic Traceloop LLM observability guide (docs.newrelic.com/docs/opentelemetry/get-started/traceloop-llm-observability/traceloop-llm-observability-intro/).

Portkey Traceloop integration docs (portkey.ai/docs/integrations/tracing-providers/traceloop). IBM Instana Traceloop instrumentation docs (ibm.com/docs/en/instana-observability/1.0.303). Middleware Traceloop guides (docs.middleware.io/llm-observability/traceloop/nextjs).

Inspektor Gadget traceloop gadget docs (inspektor-gadget.io/docs/latest/gadgets/traceloop/). Calcalist: ServiceNow acquires Traceloop (calcalistech.com/ctechnews/article/sjghwiqf11e). PitchBook Traceloop company profile (pitchbook.com/profiles/company/528696-73).

Entrepreneur News Network: ServiceNow Acquires Israeli AI Startup Traceloop (entrepreneurnewsnetwork.com/2026/03/03/servicenow-acquires-israeli-ai-startup-traceloop/).

Frequently Asked Questions

What is Traceloop used for?

Traceloop is used for LLM observability: it records every model call, vector-database call, workflow, and tool call your app makes as OpenTelemetry traces, so you can see latency, token use, prompts, and errors for each request. It is built for developers whose LLM apps have reached production and can no longer be debugged by reading final answers alone.

Is Traceloop free?

Yes, the Free Forever plan costs 0 dollars per month and covers up to 50,000 spans per month with 24 hours of data retention, including the monitoring and evaluation dashboards. The underlying OpenLLMetry instrumentation is Apache 2.0 licensed and free to use with any of the 25-plus supported backends, even if you never pay Traceloop anything.

Do I need to import Traceloop before my LLM libraries?

No, not in Python. The import-before-LLM-libraries rule is a TS/JS rule, according to the official troubleshooting page. In Python, what matters is calling Traceloop.init() before your app makes its first LLM call or creates its first agent.

What is the difference between Traceloop and OpenLLMetry?

OpenLLMetry is the open-source OpenTelemetry extension that instruments LLM apps, and Traceloop is the company and the hosted dashboard built around it. You can use OpenLLMetry on its own and send traces to any observability platform, or use it with Traceloop Cloud for the dashboards, monitors, and evaluations.

Can I self-host Traceloop?

Yes, the full Traceloop platform can be deployed in your own infrastructure with Helm on Kubernetes, using ClickHouse, Kafka, PostgreSQL, and S3 storage, including air-gapped environments. If full self-hosting is more than you need, you can also keep the SDK and point TRACELOOP_BASE_URL at your own OpenTelemetry Collector or another backend.