> ## Documentation Index
> Fetch the complete documentation index at: https://futureagi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracing

> Reference for tracing and telemetry in the Trace AI Python SDK.

# 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.

```python theme={null}
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.

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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)
```

***