chore: import upstream snapshot with attribution

apps/opik-documentation/python-sdk-docs/source/context_manager/distributed_headers.rst

@@ -0,0 +1,90 @@
+distributed_headers
+===================
+
+.. autofunction:: opik.decorator.context_manager.distributed_headers
+
+Examples
+--------
+
+Basic usage in a server endpoint
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from opik.decorator.context_manager import distributed_headers
+   from fastapi import FastAPI, Request
+
+   app = FastAPI()
+
+   @app.post("/generate_response")
+   def generate_llm_response(request: Request) -> str:
+       # Extract distributed headers from the incoming request
+       headers = {
+           "opik_trace_id": request.headers.get("opik_trace_id"),
+           "opik_parent_span_id": request.headers.get("opik_parent_span_id"),
+       }
+
+       # Use the context manager to handle distributed headers
+       with distributed_headers(headers):
+           result = my_llm_application()
+
+       return result
+
+With flush enabled
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from opik.decorator.context_manager import distributed_headers
+
+   def process_request(headers_dict):
+       # Flush data immediately after the root span is processed
+       with distributed_headers(headers_dict, flush=True):
+           # Your processing logic here
+           pass
+
+Using with the track decorator
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from opik import track
+   from opik.decorator.context_manager import distributed_headers
+   from flask import Flask, request
+
+   app = Flask(__name__)
+
+   @track()
+   def my_llm_function(prompt: str) -> str:
+       # Your LLM logic here
+       return "response"
+
+   @app.route("/api/generate", methods=["POST"])
+   def api_endpoint():
+       # Extract headers from the request
+       headers = {
+           "opik_trace_id": request.headers.get("opik_trace_id"),
+           "opik_parent_span_id": request.headers.get("opik_parent_span_id"),
+       }
+
+       # Create distributed trace context
+       with distributed_headers(headers):
+           result = my_llm_function(prompt=request.json.get("prompt"))
+
+       return {"result": result}
+
+Error handling
+~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   from opik.decorator.context_manager import distributed_headers
+
+   try:
+       with distributed_headers(incoming_headers):
+           # Code that might fail
+           result = risky_operation()
+   except Exception as e:
+       # The context manager automatically logs the error
+       # and attaches error information to the root span
+       print(f"Operation failed: {e}")

apps/opik-documentation/python-sdk-docs/source/context_manager/index.rst

@@ -0,0 +1,67 @@
+Context Managers
+================
+
+Opik provides context managers for creating and managing traces and spans in your application. These context managers allow you to easily instrument your code with tracing capabilities while ensuring proper cleanup and error handling.
+
+Context managers are particularly useful when you need fine-grained control over trace and span creation, or when working with code that doesn't fit well with the `@track` decorator pattern.
+
+Available Context Managers
+---------------------------
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   start_as_current_span
+   start_as_current_trace
+   distributed_headers
+
+Key Features
+------------
+
+- **Automatic Error Handling**: Context managers automatically capture and log errors that occur within their scope
+- **Distributed Tracing**: Support for distributed tracing headers to maintain trace context across service boundaries
+- **Flexible Configuration**: Rich set of parameters for customizing trace and span behavior
+- **Resource Management**: Automatic cleanup and flushing of trace data
+- **Nested Support**: Context managers can be nested to create hierarchical trace structures
+
+Basic Usage Pattern
+-------------------
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_trace("my-trace", project_name="my-project") as trace:
+        # Your application logic here
+        trace.input = {"user_query": "Explain quantum computing"}
+        trace.output = {"response": "Quantum computing is..."}
+        trace.tags = ["chat"]
+        trace.metadata = {"model": "gpt-4", "temperature": 0.7}
+
+        # Basic span creation
+        with opik.start_as_current_span("llm-call", type="llm", project_name="my-project") as span:
+            # Your LLM call here
+            span.input = {"prompt": "Explain quantum computing"}
+            span.output = {"response": "Quantum computing is..."}
+            span.model = "gpt-4"
+            span.provider = "openai"
+            span.usage = {
+                "prompt_tokens": 10,
+                "completion_tokens": 50,
+                "total_tokens": 60
+            }
+
+
+When to Use Context Managers
+----------------------------
+
+Use context managers when:
+
+- You need explicit control over trace/span lifecycle
+- Working with code that can't be easily decorated
+- Implementing custom error handling patterns
+- Building distributed tracing across service boundaries
+- Creating complex nested trace hierarchies
+
+For simpler use cases, consider using the `@track` decorator instead.

apps/opik-documentation/python-sdk-docs/source/context_manager/start_as_current_span.rst

@@ -0,0 +1,71 @@
+start_as_current_span
+=====================
+
+.. autofunction:: opik.start_as_current_span
+
+Examples
+--------
+
+Basic usage
+~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_span("my_operation") as span:
+       # Your code here
+       span.metadata["custom_key"] = "custom_value"
+       print("Executing operation...")
+
+With input and output data
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_span(
+       name="llm_completion",
+       type="llm",
+       input={"prompt": "What is the capital of France?"},
+       output={"response": "The capital of France is Paris."},
+       tags=["llm", "completion"],
+       metadata={"model": "gpt-3.5-turbo"}
+   ) as span:
+       # Your LLM code here
+       pass
+
+With distributed tracing
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import os
+   import opik
+
+   # extract headers from environment
+   distributed_trace_headers = os.environ.get("opik_distributed_trace_headers")
+
+   with opik.start_as_current_span(
+       "process_request",
+       opik_distributed_trace_headers=distributed_trace_headers
+   ) as span:
+       # Your code here
+       pass
+
+Error handling
+~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   try:
+       with opik.start_as_current_span("risky_operation") as span:
+           # Code that might fail
+           raise ValueError("Something went wrong")
+   except ValueError as e:
+       # The span will automatically capture error information
+       print(f"Operation failed: {e}")
+       # Error details are stored in span.error_info

apps/opik-documentation/python-sdk-docs/source/context_manager/start_as_current_trace.rst

@@ -0,0 +1,87 @@
+start_as_current_trace
+======================
+
+.. autofunction:: opik.start_as_current_trace
+
+Examples
+--------
+
+Basic usage
+~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_trace("my_trace") as trace:
+       # Your code here
+       trace.metadata["custom_key"] = "custom_value"
+       print("Executing trace...")
+
+With input and output data
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_trace(
+       name="user_query_processing",
+       input={"user_question": "What is machine learning?"},
+       output={"answer": "Machine learning is a subset of AI..."},
+       tags=["user_query", "ai"],
+       metadata={"session_id": "abc123"}
+   ) as trace:
+       # Your processing code here
+       pass
+
+With conversational threads support using `thread_id` identifier
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+   import threading
+
+   with opik.start_as_current_trace(
+       "chatbot_conversation",
+       project_name="my_project",
+       thread_id="00f067aa0ba902b7",
+   ) as trace:
+       # Your processing code here
+       pass
+
+
+Error handling
+~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   try:
+       with opik.start_as_current_trace("risky_trace") as trace:
+           # Code that might fail
+           raise RuntimeError("Something went wrong")
+   except RuntimeError as e:
+       # The trace will automatically capture error information
+       print(f"Trace failed: {e}")
+       # Error details are stored in trace.error_info
+
+Nested spans within a trace
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   import opik
+
+   with opik.start_as_current_trace("main_workflow") as trace:
+       # Main workflow code
+       
+       with opik.start_as_current_span("sub_operation_1") as span1:
+           # First sub-operation
+           pass
+       
+       with opik.start_as_current_span("sub_operation_2") as span2:
+           # Second sub-operation
+           pass