{"id":6778,"library":"promptflow-tracing","title":"Prompt Flow Tracing","description":"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.","status":"active","version":"1.18.4","language":"en","source_language":"en","source_url":"https://github.com/microsoft/promptflow","tags":["AI","LLM","tracing","observability","OpenTelemetry","prompt engineering"],"install":[{"cmd":"pip install promptflow-tracing","lang":"bash","label":"Install `promptflow-tracing`"},{"cmd":"pip install promptflow","lang":"bash","label":"Install `promptflow` for full experience (includes tracing)"}],"dependencies":[{"reason":"Often 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.","package":"promptflow","optional":true},{"reason":"Provides 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.","package":"promptflow-devkit","optional":true},{"reason":"Required for the quickstart example to demonstrate tracing LLM calls, but not a direct dependency of `promptflow-tracing` itself.","package":"openai","optional":true}],"imports":[{"symbol":"start_trace","correct":"from promptflow.tracing import start_trace"},{"symbol":"trace","correct":"from promptflow.tracing import trace"}],"quickstart":{"code":"import os\nfrom openai import OpenAI\nfrom promptflow.tracing import start_trace, trace\n\n# Ensure OPENAI_API_KEY is set in your environment\n# or pass it explicitly to OpenAI(api_key=...) if not using env var.\n# For Azure OpenAI, set AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION, AZURE_OPENAI_DEPLOYMENT_NAME\n\n# Start tracing. This will instrument supported libraries like OpenAI.\nstart_trace()\n\nclient = OpenAI(api_key=os.environ.get('OPENAI_API_KEY', ''))\n\n@trace\ndef poetic_explanation(concept: str) -> str:\n    try:\n        completion = client.chat.completions.create(\n            model=\"gpt-3.5-turbo\",\n            messages=[\n                {\"role\": \"system\", \"content\": \"You are a poetic assistant, skilled in explaining complex programming concepts with creative flair.\"}, \n                {\"role\": \"user\", \"content\": f\"Compose a short poem that explains the concept of {concept} in programming.\"}\n            ]\n        )\n        return completion.choices[0].message.content\n    except Exception as e:\n        print(f\"Error calling OpenAI: {e}\")\n        return \"Failed to get a poetic explanation.\"\n\n\nif os.environ.get('OPENAI_API_KEY'): # Only run if API key is present\n    print(\"--- Tracing LLM call with start_trace() ---\")\n    poem = poetic_explanation(\"recursion\")\n    print(poem)\n    print(\"\\nCheck your console for a URL to the trace UI (requires promptflow-devkit).\")\nelse:\n    print(\"Skipping quickstart: OPENAI_API_KEY environment variable not set.\")","lang":"python","description":"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."},"warnings":[{"fix":"To enable tracing, call `promptflow.tracing.start_trace()` in your application code or ensure appropriate environment variables are set for your deployment environment.","message":"Tracing 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.","severity":"breaking","affected_versions":">=1.17.0"},{"fix":"Upgrade your Python environment to 3.9 or newer (up to <4.0 as per PyPI metadata).","message":"Python 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.","severity":"deprecated","affected_versions":">=1.17.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Users 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Since 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.","severity":"gotcha","affected_versions":">=1.8.0"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}