Session

Detailed descriptions of classes and methods related to Phoenix sessions

phoenix.launch_app

def launch_app(
    primary: Optional[Dataset] = None,
    reference: Optional[Dataset] = None,
    corpus: Optional[Dataset] = None,
    trace: Optional[TraceDataset] = None,
    host: Optional[str] = None,
    port: Optional[int] = None,
    run_in_thread: Optional[bool] = True,
) -> Session

Launches and returns a new Phoenix session.

All parameters are optional and launch_app() launches a Phoenix session with no data and is always ready to receive trace data your LLM applications in real time. See LLM Traces for more.

launch_app can accept one or two Dataset instances as arguments. If the app is launched with a single dataset, Phoenix provides model performance and data quality metrics, but not drift metrics. If the app is launched with two datasets, Phoenix provides drift metrics in addition to model performance and data quality metrics. When two datasets are provided, the reference dataset serves as a baseline against which to compare the primary dataset. Common examples of primary and reference datasets include production vs. training or challenger vs. champion.

[source]

Parameters

• primary (Optional[Dataset]): The dataset that is of primary interest as the subject of investigation or evaluation.

• reference (Optional[Dataset]): If provided, the reference dataset serves as a baseline against which to compare the primary dataset.

• corpus (Optional[Dataset]): If provided, the corpus dataset represents the corpus data from which documents are retrieved in an Retrieval-Augmented Generation (RAG) use case. See Corpus Data for more on how to import this data, and Retrieval (RAG) for more bout the use case.

• trace (Optional[TraceDataset]): If provided, a trace dataset containing spans. Phoenix can be started with or without a dataset and will always be able to receive traces in real time from your LLM application. See LLM Traces for more.

• host (Optional[str]): The host on which the server runs. It can also be set using environment variable PHOENIX_HOST, otherwise it defaults to 127.0.0.1. Most users don't need to worry this parameter.

• port (Optional[int]): The port on which the server listens. It can also be set using environment variable PHOENIX_PORT, otherwise it defaults to 6006. This parameter is useful if 6006 is already occupied by a separate application.

• run_in_thread (bool): Whether the server should run in a Thread or Process. Defaults to True. This can be turned off if there is a problem starting a thread in a Jupyter Notebook.

• default_umap_parameters (Optional Dict[str, Union[int, float]]): default UMAP parameters to use when launching the point-cloud eg: {"n_neighbors": 10, "n_samples": 5, "min_dist": 0.5}

Returns

The newly launched session as an instance of Session.

Usage

Launch Phoenix as a collector of LLM Traces generated by your LLM applications. By default the collector listens on port 6006.

session = px.launch_app()

Launch Phoenix with primary and reference datasets prim_ds and ref_ds, both instances of Dataset, with

session = px.launch_app(prim_ds, ref_ds)

Alternatively, launch Phoenix with a single dataset ds, an instance of Dataset, with

session = px.launch_app(ds)

Then session is an instance of Session that can be used to open the Phoenix UI in an inline frame within the notebook or in a separate browser tab or window.

phoenix.active_session

def active_session() -> Optional[Session]

Returns the active Phoenix Session if one exists, otherwise, returns None.

[session]

Usage

Suppose you previously ran

px.launch_app()

without assigning the returned Session instance to a variable. If you later find that you need access to the running session object, run

session = px.active_session()

Then session is an instance of Session that can be used to open the Phoenix UI in an inline frame within your notebook or in a separate browser tab or window.

phoenix.close_app

def close_app() -> None

Closes the running Phoenix session, if it exists.

The Phoenix server will continue running in the background until it is explicitly closed, even if the Jupyter server and kernel are stopped.

[source]

Usage

Suppose you previously launched a Phoenix session with launch_app. You can close the running session with

px.close_app()

phoenix.Session

A session that maintains the state of the Phoenix app. Obtain the active session as follows.

session = px.active_session()

Methods

• view(height: int = 1000) -> IPython.display.IFrame Displays the Phoenix UI for a running session within an inline frame in the notebook. Parameters

  • height (int = 1000): The height in pixels of the inline frame element displaying the Phoenix UI within the notebook. Used to adjust the height of the inline frame to the desired height.

• get_spans_dataframe -> pandas.DataFrame Returns spans in a pandas.dataframe. Filters can be applied. See LLM Traces for more about tracing your LLM application. Parameters

  • filter_condition (Optional[str]): A Python expression for filtering spans. See Usage below for examples.

  • start_time (Optional[datetime]): A Python datetime object for filtering spans by time.

  • stop_time (Optional[datetime]): A Python datetime object for filtering spans by time.

  • root_spans_only (Optional[bool]): Whether to return only root spans, i.e. spans without parents. Defaults to False.

Attributes

• url (str): The URL of the running Phoenix session. Can be copied and pasted to open the Phoenix UI in a new browser tab or window.

• exports (List[pandas.DataFrame]): A list of pandas dataframes containing exported data, sorted in chronological order. Exports of UMAP cluster data and can be initiated in the clustering UI.

Usage

Phoenix users should not instantiate their own phoenix.Session instances. They interact with this API only when an instance of the class is returned by launch_app or active_session.

Launch Phoenix with primary and reference datasets prim_ds and ref_ds, both instances of phoenix.Dataset, with

session = px.launch_app(prim_ds, ref_ds)

Alternatively, launch Phoenix with a single dataset ds, an instance of phoenix.Dataset, with

session = px.launch_app(ds)

Open the Phoenix UI in an inline frame within your notebook with

session.view()

You can adjust the height of the inline frame by passing the desired height (number of pixels) to the height parameter. For example, instead of the line above, run

session.view(height=1200)

to open an inline frame of height 1200 pixels.

As an alternative to an inline frame within your notebook, you can open the Phoenix UI in a new browser tab or window by running

session.url

and copying and pasting the URL.

Once a cluster or subset of your data is selected in the UI, it can be saved by clicking the "Export" button. You can then access your exported data in your notebook via the exports property on your session object, which returns a list of dataframes containing each export.

session.exports

Exported dataframes are listed in chronological order. To access your most recent export, run

session.exports[-1]

Get LLM Spans As DataFrame

Get all available spans. See LLM Traces on how to trace your LLM applications.

session.get_spans_dataframe()

Get spans associated with calls to LLMs.

session.get_spans_dataframe("span_kind == 'LLM'")

Get spans associated with calls to retrievers in a Retrieval Augmented Generation use case.

session.get_spans_dataframe("span_kind == 'RETRIEVER'")

Environment Variables

Some settings of the Phoenix Session can be configured through the environment variables below.

• PHOENIX_PORT The port on which the server listens.

• PHOENIX_HOST The host on which the server listens.

Below is an example of how to set up the port parameter as an environment variable.

import os
os.environ["PHOENIX_PORT"] = "54321"