tessl/pypi-openinference-instrumentation

OpenInference instrumentation utilities for tracking application metadata such as sessions, users, and custom metadata using Python context managers

—

Pending

Overview

Eval results

Files

Context Management

Name: tessl/pypi-openinference-instrumentation
Author: tessl

Context management utilities for tracking important application metadata such as sessions, users, metadata, tags, and prompt templates using Python context managers. These utilities integrate with OpenTelemetry context to ensure metadata is automatically attached to all spans created within their scope.

Capabilities

Session Tracking

Track multi-turn conversations and group related operations by session.

class using_session:
    """
    Context manager to add session ID to the current OpenTelemetry Context.
    
    Args:
        session_id (str): The session identifier to track
    """
    def __init__(self, session_id: str) -> None: ...
    def __enter__(self) -> Self: ...
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
    async def __aenter__(self) -> Self: ...
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...

Usage Example:

from openinference.instrumentation import using_session

with using_session("conversation-abc-123"):
    # All spans created here will have session.id = "conversation-abc-123"
    response = llm_client.chat.completions.create(...)
    
# Can also be used as a decorator
@using_session("batch-process-456")
def process_batch():
    # All spans in this function will have the session ID
    pass

User Tracking

Track different conversations and operations by user.

class using_user:
    """
    Context manager to add user ID to the current OpenTelemetry Context.
    
    Args:
        user_id (str): The user identifier to track
    """
    def __init__(self, user_id: str) -> None: ...
    def __enter__(self) -> Self: ...
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
    async def __aenter__(self) -> Self: ...
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...

Usage Example:

from openinference.instrumentation import using_user

with using_user("user-789"):
    # All spans created here will have user.id = "user-789"
    personalized_response = generate_response(user_preferences)

Metadata Tracking

Add custom metadata to provide additional context for operations.

class using_metadata:
    """
    Context manager to add metadata to the current OpenTelemetry Context.
    
    Args:
        metadata (Dict[str, Any]): Dictionary of metadata key-value pairs
    """
    def __init__(self, metadata: Dict[str, Any]) -> None: ...
    def __enter__(self) -> Self: ...
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
    async def __aenter__(self) -> Self: ...
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...

Usage Example:

from openinference.instrumentation import using_metadata

metadata = {
    "user_tier": "premium",
    "region": "us-west-2",
    "feature_flags": {"new_ui": True, "beta_model": False}
}

with using_metadata(metadata):
    # All spans will have metadata JSON-serialized and attached
    result = complex_operation()

Tag Tracking

Add tags for filtering and categorization.

class using_tags:
    """
    Context manager to add tags to the current OpenTelemetry Context.
    
    Args:
        tags (List[str]): List of string tags
    """
    def __init__(self, tags: List[str]) -> None: ...
    def __enter__(self) -> Self: ...
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
    async def __aenter__(self) -> Self: ...
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...

Usage Example:

from openinference.instrumentation import using_tags

tags = ["production", "critical", "customer-facing"]

with using_tags(tags):
    # All spans will have tag.tags = ["production", "critical", "customer-facing"]
    critical_operation()

Prompt Template Tracking

Track prompt templates with their versions and variables for prompt management.

class using_prompt_template:
    """
    Context manager to add prompt template information to the current OpenTelemetry Context.
    
    Args:
        template (str): The prompt template string
        version (str): Version identifier for the template
        variables (Optional[Dict[str, Any]]): Variables used in the template
    """
    def __init__(
        self,
        *,
        template: str = "",
        version: str = "",
        variables: Optional[Dict[str, Any]] = None,
    ) -> None: ...
    def __enter__(self) -> Self: ...
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
    async def __aenter__(self) -> Self: ...
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...

Usage Example:

from openinference.instrumentation import using_prompt_template

template = "Generate a {style} summary of the following text: {text}"
variables = {"style": "concise", "text": user_input}

with using_prompt_template(
    template=template,
    version="v2.1",
    variables=variables
):
    # Spans will include prompt template metadata
    summary = llm.generate(prompt)

Combined Attributes

Convenient context manager for using multiple attribute types together.

class using_attributes:
    """
    Context manager to add multiple attributes to the current OpenTelemetry Context.
    Combines functionality of other context managers for convenience.
    
    Args:
        session_id (str): Session identifier
        user_id (str): User identifier  
        metadata (Optional[Dict[str, Any]]): Custom metadata
        tags (Optional[List[str]]): List of tags
        prompt_template (str): Prompt template string
        prompt_template_version (str): Template version
        prompt_template_variables (Optional[Dict[str, Any]]): Template variables
    """
    def __init__(
        self,
        *,
        session_id: str = "",
        user_id: str = "",
        metadata: Optional[Dict[str, Any]] = None,
        tags: Optional[List[str]] = None,
        prompt_template: str = "",
        prompt_template_version: str = "",
        prompt_template_variables: Optional[Dict[str, Any]] = None,
    ) -> None: ...
    def __enter__(self) -> Self: ...
    def __exit__(self, exc_type, exc_value, traceback) -> None: ...
    async def __aenter__(self) -> Self: ...
    async def __aexit__(self, exc_type, exc_value, traceback) -> None: ...

Usage Example:

from openinference.instrumentation import using_attributes

with using_attributes(
    session_id="chat-session-123",
    user_id="user-456", 
    metadata={"tier": "premium", "region": "us-east"},
    tags=["chatbot", "support"],
    prompt_template="Answer this question: {question}",
    prompt_template_version="v1.0",
    prompt_template_variables={"question": user_question}
):
    # All context attributes are applied at once
    response = chatbot.respond(user_question)

Context Attribute Extraction

Extract attributes from the current OpenTelemetry context.

def get_attributes_from_context() -> Iterator[Tuple[str, AttributeValue]]:
    """
    Extracts all OpenInference attributes from the current OpenTelemetry context.
    
    Returns:
        Iterator[Tuple[str, AttributeValue]]: Yields (attribute_name, attribute_value) pairs
    """

Usage Example:

from openinference.instrumentation import get_attributes_from_context, using_session

with using_session("test-session"):
    # Get all current context attributes
    for attr_name, attr_value in get_attributes_from_context():
        print(f"{attr_name}: {attr_value}")
    # Output: session.id: test-session

Context Manager Features

All context managers support:

Synchronous usage: with using_session("id"):
Asynchronous usage: async with using_session("id"):
Decorator usage: @using_session("id")
Nested usage: Context managers can be nested or combined
Exception safety: Contexts are properly cleaned up even if exceptions occur

Attribute Mapping

The context managers map to the following OpenInference span attributes:

using_session → session.id
using_user → user.id
using_metadata → metadata (JSON-serialized)
using_tags → tag.tags (list)
using_prompt_template → llm.prompt_template.* attributes

Install with Tessl CLI

npx tessl i tessl/pypi-openinference-instrumentation

docs

attribute-generation.md

configuration.md

context-management.md

tessl/pypi-openinference-instrumentation