session#

phoenix.launch_app#

launch_app(reference=None, corpus=None, trace=None, default_umap_parameters=None, host=None, port=None, run_in_thread=True, notebook_environment=None, use_temp_dir=True)#

Launches the phoenix application and returns a session to interact with.

Parameters:

  • primary (Dataset, optional) – The primary dataset to analyze

  • reference (Dataset, optional) – The reference dataset to compare against. If not provided, drift analysis will not be available.

  • corpus (Dataset, optional) – The dataset containing corpus for LLM context retrieval.

  • trace (TraceDataset, optional) – The trace dataset containing the trace data.

  • host (str, optional) – 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.

  • port (int, optional) – The port on which the server listens. When using traces this should not be used and should instead set the environment variable PHOENIX_PORT. Defaults to 6006.

  • run_in_thread (bool, optional, default=True) – Whether the server should run in a Thread or Process.

  • default_umap_parameters (Dict[str, Union[int, float]], optional, default=None) – User specified default UMAP parameters eg: {“n_neighbors”: 10, “n_samples”: 5, “min_dist”: 0.5}

  • notebook_environment (str, optional, default=None) – The environment the notebook is running in. This is either ‘local’, ‘colab’, or ‘sagemaker’. If not provided, phoenix will try to infer the environment. This is only needed if there is a failure to infer the environment.

  • use_temp_dir (bool, optional, default=True) – Whether to use a temporary directory to store the data. If set to False, the data will be stored in the directory specified by PHOENIX_WORKING_DIR environment variable via SQLite.

Returns:

session – The session object that can be used to view the application

Return type:

Session

Examples

>>> import phoenix as px
>>> # construct an inference set to analyze
>>> inferences = px.Inferences(...)
>>> session = px.launch_app(inferences)

Usage

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

import phoenix as px

Launch Phoenix with primary and reference inferences prim_inf_ and ref_inf_, both instances of Inferences, with:

session = px.launch_app(prim_inf_, ref_inf_)

Alternatively, launch Phoenix with a single dataset inf, an instance of Inferences, with:

session = px.launch_app(inf)

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#

active_session()#

Returns the active session if one exists, otherwise returns None

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#

close_app()#

Closes the phoenix application. The application server is shut down and will no longer be accessible.

Parameters:

delete_data (bool, optional) – If set to true, all stored phoenix data, including traces and evaluations. Default False.

Warning

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

phoenix.delete_all#

delete_all()#

Deletes the entire contents of the working directory. This will delete, traces, evaluations, and any other data stored in the working directory.

phoenix.Session#

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

session = px.active_session()

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 or active_session.

class Session(database_url, primary_inferences, reference_inferences=None, corpus_inferences=None, trace_dataset=None, default_umap_parameters=None, host=None, port=None, notebook_env=None)#

Bases: TraceDataExtractor, ABC

Session that maintains a 1-1 shared state with the Phoenix App.

property database_url#
property exports#

Exported data sorted in descending order by modification date.

Returns:

dataframes – List of dataframes

Return type:

list

get_evaluations(project_name=None)#

Get the evaluations for a project.

Parameters:

project_name (str, optional) – The name of the project. If not provided, the project name set in the environment variable PHOENIX_PROJECT_NAME will be used. Otherwise, ‘default’ will be used.

Returns:

evaluations – A list of evaluations for the specified project.

Return type:

List[Evaluations]

notebook_env#

The notebook environment that the session is running in.

query_spans(*queries, start_time=None, end_time=None, limit=DEFAULT_SPAN_LIMIT, root_spans_only=None, project_name=None, stop_time=None, timeout=DEFAULT_TIMEOUT_IN_SECONDS)#

Queries the spans in the project based on the provided parameters.

Parameters:

  • queries (*SpanQuery) – Variable-length argument list of SpanQuery objects representing the queries to be executed.

  • start_time (datetime, optional) – datetime representing the start time of the query.

  • end_time (datetime, optional) – datetime representing the end time of the query.

  • root_spans_only (boolean, optional) – whether to include only root spans in the results.

  • project_name (string, optional) – name of the project to query. Defaults to the project name set in the environment variable PHOENIX_PROJECT_NAME or ‘default’ if not set.

Returns:

DataFrame

DataFrame or list of DataFrames containing the query results.

Return type:

results

property url#

Returns the url for the phoenix app

view(*, height=1000, slug='')#

View the session in a notebook embedded iFrame.

Parameters:

  • slug (str, optional) – the path of the app to view

  • height (int, optional) – the height of the iFrame in px. Defaults to 1000.

Returns:

the iFrame will be rendered in the notebook

Return type:

IFrame

Usage

Launch Phoenix with primary and reference inferences prim_inf and ref_inf, both instances of phoenix.Dataset, with:

session = px.launch_app(prim_inf, ref_inf)

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

session = px.launch_app(inf)

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.

..code:

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'")