---
description: Detailed descriptions of classes and methods related to Phoenix sessions
---
# Session
## phoenix.launch\_app
```python
def launch_app(
primary: Optional[Inferences] = None,
reference: Optional[Inferences] = None,
corpus: Optional[Inferences] = None,
trace: Optional[TraceDataset] = None,
host: Optional[str] = None,
port: Optional[int] = None,
run_in_thread: Optional[bool] = True,
use_temp_dir: Optional[bool] = True,
) -> Session
```
Launches and returns a new Phoenix session in a python notebook.
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](../tracing/llm-traces/) for more.
`launch_app` can accept one or two [Inferences](../inferences/inference-and-schema.md#phoenix.inferences) 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 sets of inferences, Phoenix provides drift metrics in addition to model performance and data quality metrics. When two sets of inferences are provided, the reference inference collection serves as a baseline against which to compare the primary inference collection. Common examples of primary and reference inferences include production vs. training or challenger vs. champion.
**\[**[**source**](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/session/session.py)**]**
### Parameters
* **primary** (Optional\[[Inferences](../inferences/inference-and-schema.md#phoenix.inferences)]): The dataset that is of primary interest as the subject of investigation or evaluation.
* **reference** (Optional\[[Inferences](../inferences/inference-and-schema.md#phoenix.inferences)]): If provided, the reference dataset serves as a baseline against which to compare the primary dataset.
* **corpus** (Optional\[[Inferences](../inferences/inference-and-schema.md#phoenix.inferences)]): 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](../inferences/how-to-inferences/define-your-schema/corpus-data.md) for more on how to import this data, and [Retrieval (RAG)](../inferences/how-to-inferences/define-your-schema/retrieval-rag.md) 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](../tracing/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.
* **use\_temp\_dir** (bool): By default, data will be persisted in a temp directory. Set this to false to write to the directory specified by the PHOENIX\_WORKING\_DIR environment variable. See [#environment-variables](../deployment/configuration.md#environment-variables "mention")
* **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](session.md#phoenix.session).
### Usage
Launch Phoenix as a collector of [LLM Traces](../tracing/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 inferences `prim_inf_` and `ref_inf_`, both instances of [Inferences](../inferences/inference-and-schema.md#phoenix.inferences), with
```python
session = px.launch_app(prim_inf_, ref_inf_)
```
Alternatively, launch Phoenix with a single dataset `inf`, an instance of [Inferences](../inferences/inference-and-schema.md#phoenix.inferences), with
```python
session = px.launch_app(inf)
```
Then `session` is an instance of [Session](session.md#phoenix.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
```python
def active_session() -> Optional[Session]
```
Returns the active Phoenix `Session` if one exists, otherwise, returns `None`.
**\[**[**session**](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/session/session.py)**]**
### Usage
Suppose you previously ran
```python
px.launch_app()
```
without assigning the returned [Session](session.md#phoenix.session) instance to a variable. If you later find that you need access to the running session object, run
```python
session = px.active_session()
```
Then `session` is an instance of [Session](session.md#phoenix.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
```python
def close_app() -> None
```
Closes the running Phoenix session, if it exists.
{% hint style="warning" %}
The Phoenix server will continue running in the background until it is explicitly closed, even if the Jupyter server and kernel are stopped.
{% endhint %}
**\[**[**source**](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/session/session.py)**]**
### Usage
Suppose you previously launched a Phoenix session with [launch\_app](session.md#phoenix.launch_app). You can close the running session with
```python
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](../tracing/llm-traces/) for more about tracing your LLM application.\
\
**Parameters**
* **filter\_condition** (Optional\[str]): A Python expression for filtering spans. See [Usage](session.md#usage-3) 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
{% hint style="warning" %}
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](session.md#phoenix.launch_app) or [active\_session](session.md#phoenix.active_session).
{% endhint %}
Launch Phoenix with primary and reference inferences `prim_inf` and `ref_inf`, both instances of [phoenix.Dataset](../inferences/inference-and-schema.md#phoenix.inferences), with
```python
session = px.launch_app(prim_inf, ref_inf)
```
Alternatively, launch Phoenix with a single dataset `ds`, an instance of [phoenix.Dataset](../inferences/inference-and-schema.md#phoenix.inferences), with
```python
session = px.launch_app(inf)
```
Open the Phoenix UI in an inline frame within your notebook with
```python
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
```python
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
```python
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.
```python
session.exports
```
Exported dataframes are listed in chronological order. To access your most recent export, run
```python
session.exports[-1]
```
#### Get LLM Spans As DataFrame
Get all available spans. See [LLM Traces](../tracing/llm-traces/) on how to trace your LLM applications.
```python
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'")
## phoenix.delete\_all
```python
def delete_all(prompt_before_delete: Optional[bool] = True) -> None:
```
Removes all persisted data under the **PHOENIX\_WORKING\_DIR** to reset your session on next launch.
## Environment Variables
Some settings of the Phoenix [Session](session.md#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.
```python
import os
os.environ["PHOENIX_PORT"] = "54321"
```