Tracing & Telemetry

The tracing module provides utilities for registering and managing OpenTelemetry-compatible tracing for your projects, including project registration, span attributes, and tracer provider configuration.

register Function

Registers a new tracing provider for your project and configures telemetry for experiment or observe runs.

def register(
    *,
    project_name: Optional[str] = None,
    project_type: Optional[ProjectType] = ProjectType.EXPERIMENT,
    project_version_name: Optional[str] = None,
    eval_tags: Optional[List[EvalTag]] = None
    metadata: Optional[Dict[str, Any]] = None,
    batch: bool = False,
    set_global_tracer_provider: bool = False,
    headers: Optional[Dict[str, str]] = None,
    verbose: bool = True,
) -> _TracerProvider

Arguments:

• project_name (Optional[str]): Name of the project. If not provided, will be read from environment variables.
• project_type (Optional[ProjectType]): Type of the project (EXPERIMENT or OBSERVE). Default: EXPERIMENT.
• project_version_name (Optional[str]): Version name for the project.
• eval_tags (Optional[List[EvalTag]]): List of evaluation tags.
• metadata (Optional[Dict[str, Any]]): Additional metadata for the project.
• batch (bool): Whether to use batch span processing. Default: False.
• set_global_tracer_provider (bool): If True, sets this provider as the global OpenTelemetry tracer provider.
• headers (Optional[Dict[str, str]]): Additional headers for the exporter.
• verbose (bool): If True, prints configuration details.

Returns:

• _TracerProvider: The configured tracer provider.

Raises:

• ValidationError: If arguments are invalid or duplicate custom eval names are provided.

TracerProvider Class

An extension of opentelemetry.sdk.trace.TracerProvider with Future AGI aware defaults.

class TracerProvider(_TracerProvider):
    def __init__(
        self,
        *args: Any,
        endpoint: Optional[str] = None,
        verbose: bool = True,
        **kwargs: Any,
    )

Arguments:

• endpoint (str, optional): The collector endpoint to which spans will be exported.
• verbose (bool): If True, configuration details will be printed to stdout.

Methods:

• add_span_processor(...): Registers a new SpanProcessor for this TracerProvider.

Span and Message Attribute Constants

The following classes provide constants for span and message attributes used in tracing:

• SpanAttributes
• MessageAttributes
• MessageContentAttributes
• ImageAttributes
• AudioAttributes
• DocumentAttributes
• RerankerAttributes
• EmbeddingAttributes
• ToolCallAttributes
• ToolAttributes

Each class contains string constants for OpenTelemetry span attributes, such as:

SpanAttributes.LLM_MODEL_NAME  # "llm.model_name"
SpanAttributes.LLM_PROVIDER    # "llm.provider"
SpanAttributes.LLM_PROMPTS     # "llm.prompts"
MessageAttributes.MESSAGE_ROLE # "message.role"
...

Refer to the SDK source or inline docstrings for the full list of available attributes.

Enum Types

The tracing module also provides several enums for project and span types:

• ProjectType: EXPERIMENT, OBSERVE
• EvalTagType
• EvalSpanKind
• EvalName
• Endpoints
• FiSpanKindValues
• FiMimeTypeValues
• FiLLMSystemValues
• FiLLMProviderValues

Example Usage with LangChain Instrumentor

from fi_instrumentation import register, ProjectType
from traceai_langchain import LangChainInstrumentor

# Register a tracer provider for an experiment project
tracer_provider = register(
    project_name="My Project",
    project_type=ProjectType.OBSERVE,
)

# Instrument LangChain chain
LangChainInstrumentor().instrument(tracer_provider=tracer_provider)