Registry / llm-agents / promptflow-tracing

promptflow-tracing

library1.18.5pypypi✓ verified 87d ago

The `promptflow-tracing` package provides tracing capabilities for Prompt Flow, enabling the capture and visualization of internal execution processes for both DAG and Flex flows. It's designed to be compatible with OpenTelemetry, offering comprehensive observability for LLM-based applications, including those using frameworks like Langchain or OpenAI. The current version is 1.18.4, and the library is actively developed with frequent releases.

llm-agents observability ai-ml

pip install promptflow-tracing

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PROMPTFLOW-TRACING

promptflow-tracing

llm-agentspythonv1.18.5

Install

15.8s avg

Import

4498ms

Disk

61MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.18.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.940 runs

installs and imports cleanly · install 0.0s · import 4.725s · 62.2MB

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 15.8s · import 4.271s · 62MB

61MB installed

● package 61MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

start_trace

✓ from promptflow.tracing import start_trace

trace

✓ from promptflow.tracing import trace

This quickstart demonstrates how to enable tracing for LLM calls (e.g., OpenAI) using `start_trace()` and how to trace custom functions with the `@trace` decorator. Upon execution, if `promptflow-devkit` is installed, a local URL to the trace UI will be printed to the console, allowing visualization of the captured traces.

import os from openai import OpenAI from promptflow.tracing import start_trace, trace # Ensure OPENAI_API_KEY is set in your environment # or pass it explicitly to OpenAI(api_key=...) if not using env var. # For Azure OpenAI, set AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION, AZURE_OPENAI_DEPLOYMENT_NAME # Start tracing. This will instrument supported libraries like OpenAI. start_trace() client = OpenAI(api_key=os.environ.get('OPENAI_API_KEY', '')) @trace def poetic_explanation(concept: str) -> str: try: completion = client.chat.completions.create( model="gpt-3.5-turbo", messages=[ {"role": "system", "content": "You are a poetic assistant, skilled in explaining complex programming concepts with creative flair."}, {"role": "user", "content": f"Compose a short poem that explains the concept of {concept} in programming."} ] ) return completion.choices[0].message.content except Exception as e: print(f"Error calling OpenAI: {e}") return "Failed to get a poetic explanation." if os.environ.get('OPENAI_API_KEY'): # Only run if API key is present print("--- Tracing LLM call with start_trace() ---") poem = poetic_explanation("recursion") print(poem) print("\nCheck your console for a URL to the trace UI (requires promptflow-devkit).") else: print("Skipping quickstart: OPENAI_API_KEY environment variable not set.")

pf --version

Debug

Known issues

breakingTracing is now disabled by default from Prompt Flow version 1.17.0/1.17.1. Flows will no longer automatically generate traces unless explicitly enabled.

fix

To enable tracing, call `promptflow.tracing.start_trace()` in your application code or ensure appropriate environment variables are set for your deployment environment.

affects: >=1.17.0

deprecatedPython 3.8 support was dropped in Prompt Flow version 1.17.0 for security reasons. Users on Python 3.8 will need to upgrade their Python environment.

fix

Upgrade your Python environment to 3.9 or newer (up to <4.0 as per PyPI metadata).

affects: >=1.17.0

gotchaWhen deploying Prompt Flow applications with tracing enabled, a `TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'` might occur in `promptflow.tracing._trace.py`. This issue is related to incomplete token usage telemetry data during deployment.

fix

If tracing is not critical for deployment, temporarily disable it by setting the environment variable `PF_DISABLE_TRACING=true` in your deployment environment as a workaround. Investigate logs for missing token usage data if full tracing is required.

affects: All

gotchaUsers have reported instances where `promptflow-tracing` emits multiple unexpected traces (e.g., 4 traces instead of 1), especially when interacting with other frameworks like AutoGen. This may indicate default instrumentation beyond explicit calls.

fix

Review your application's interaction with `promptflow-tracing` and any integrated LLM frameworks. Explicitly manage `start_trace()` and `@trace` usage, or configure OpenTelemetry exporters to filter unwanted spans if necessary.

affects: All

gotchaSince Prompt Flow version 1.8.0, the main `promptflow` package was split into several sub-packages, including `promptflow-tracing`, `promptflow-core`, and `promptflow-devkit`. While `pip install promptflow` still installs these sub-packages, direct dependencies on `promptflow-tracing` or other specific sub-packages might require explicit installation or careful version management.

fix

For explicit control, install `promptflow-tracing` directly. For the full Prompt Flow experience including UI visualization, `pip install promptflow` is generally sufficient and recommended. Always ensure a clean environment or upgrade carefully by uninstalling old `promptflow` versions before installing newer ones if issues arise.

affects: >=1.8.0

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'promptflow.tracing'

The 'promptflow-tracing' package is not installed or is not accessible in the current Python environment.

fix

Install the package using: `pip install promptflow-tracing`

TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'

This error often occurs within the internal token collection logic of `promptflow-tracing` (specifically in `promptflow.tracing._trace.py`) when it encounters `None` values or unexpected data types (like a dictionary instead of an integer) for token counts from LLM responses or during flow deployment.

fix

Ensure LLM responses provide valid token information. If the issue persists, consider upgrading 'promptflow-tracing' to the latest version. A temporary workaround for deployment issues can be to disable tracing by setting the environment variable: `os.environ['PF_DISABLE_TRACING'] = 'true'`.

Promptflow Tracing feature is now disabled by default, with PF_DISABLE_TRACING set to true by default.

Starting with promptflow versions 1.17.0, the tracing feature is disabled by default for flows executed directly or outside of the Prompt Flow VS Code extension or Azure AI Studio UI.

fix

To enable tracing, add `from promptflow.tracing import start_trace; start_trace()` at the beginning of your application code, or set the environment variable `PF_DISABLE_TRACING='false'` before running your flow.

Upgrade

Version history

1.18.5latest on PyPI · released May 1, 2026

Audit

Dependencies

promptflowoptionalOften used alongside the main Prompt Flow SDK for an integrated experience and UI visualization, though `promptflow-tracing` can be used independently for custom OTLP collectors.

promptflow-devkitoptionalProvides the trace UI for visualization. Installed as part of `promptflow` but can be explicitly installed if `promptflow-tracing` is used standalone and visualization is desired.

openaioptionalRequired for the quickstart example to demonstrate tracing LLM calls, but not a direct dependency of `promptflow-tracing` itself.

Agent activity

25 hits · last 30 days

node

OpenAI (training)

Amazon

Resources

githubhttps://github.com/microsoft/promptflow ↗

packagehttps://pypi.org/project/promptflow-tracing/ ↗

homepagehttps://microsoft.github.io/promptflow/ ↗