Configuration

How to configure Phoenix for your needs

Ports

Phoenix is an all-in-one solution that has a tracing UI as well as a trace collector over both HTTP and gRPC. By default, the container exposes the following ports:

Port	Protocol	Endpoint	Function	Env Var
6006	HTTP	/	User interface (UI) of the web application.	PHOENIX_PORT
6006	HTTP	/v1/traces	Accepts traces in OpenTelemetry OTLP format  (Protobuf).	PHOENIX_PORT
4317	gRPC	n/a	Accepts traces in OpenTelemetry OTLP format  (Protobuf).	PHOENIX_GRPC_PORT

If the above ports need to be modified, consult the Environment Variables section below.

Environment Variables

Phoenix uses environment variables to control how data is sent, received, and stored. Here is the comprehensive list:

Server Configuration

The following environment variables will control how your phoenix server runs.

• PHOENIX_PORT: The port to run the phoenix web server. Defaults to 6006.

• PHOENIX_GRPC_PORT: The port to run the gRPC OTLP trace collector. Defaults to 4317.

• PHOENIX_HOST: The host to run the phoenix server. Defaults to 0.0.0.0

• PHOENIX_HOST_ROOT_PATH: The root path prefix for your application. If provided, allows Phoenix to run behind a reverse proxy at the specified subpath. See an example here.

• PHOENIX_WORKING_DIR: The directory in which to save, load, and export data. This directory must be accessible by both the Phoenix server and the notebook environment. Defaults to ~/.phoenix/

• PHOENIX_SQL_DATABASE_URL: The SQL database URL to use when logging traces and evals. if you plan on using SQLite, it's advised to to use a persistent volume and simply point the PHOENIX_WORKING_DIR to that volume. If URL is not specified, by default Phoenix starts with a file-based SQLite database in a temporary folder, the location of which will be shown at startup. Phoenix also supports PostgresSQL as shown below:

  • PostgreSQL, e.g. postgresql://@host/dbname?user=user&password=password or postgresql://user:password@host/dbname

  • SQLite, e.g. sqlite:///path/to/database.db

• PHOENIX_SQL_DATABASE_SCHEMA: An optional string specifying the PostgreSQL schema for the database tables. Similar to folders, schemas help organize tables outside the default public schema. If the specified schema does not exist, it will be created. This option is ignored when using SQLite.

• PHOENIX_ENABLE_PROMETHEUS: Whether to enable Prometheus metrics at port 9090. Defaults to false.

• PHOENIX_SERVER_INSTRUMENTATION_OTLP_TRACE_COLLECTOR_HTTP_ENDPOINT: Specifies an HTTP endpoint for the OTLP trace collector. Specifying this variable enables the OpenTelemetry tracer and exporter for the Phoenix server.

• PHOENIX_SERVER_INSTRUMENTATION_OTLP_TRACE_COLLECTOR_GRPC_ENDPOINT: Specifies an gRPC endpoint for the OTLP trace collector. Specifying this variable enables the OpenTelemetry tracer and exporter for the Phoenix server.

• PHOENIX_CSRF_TRUSTED_ORIGINS: A comma-separated list of origins allowed to bypass Cross-Site Request Forgery (CSRF) protection. This setting is recommended when configuring OAuth2 clients or sending password reset emails. If this variable is left unspecified or contains no origins, CSRF protection will not be enabled. In such cases, when a request includes origin or referer headers, those values will not be validated.

SMTP Configuration for Password Reset (When Auth Is Enabled)

• PHOENIX_SMTP_HOSTNAME: The SMTP hostname to use for sending password reset emails.

• PHOENIX_SMTP_PORT: The SMTP port. Defaults to 587.

• PHOENIX_SMTP_USERNAME: The SMTP username.

• PHOENIX_SMTP_PASSWORD: The SMTP password.

• PHOENIX_SMTP_MAIL_FROM: The from address in the emails. Defaults to [e-mail].

• PHOENIX_SMTP_VALIDATE_CERTS: Whether to validate the SMTP server's certificate. Defaults to true.

Client Configuration

The following environment variables will control your client or notebook environment.

• PHOENIX_NOTEBOOK_ENV: The notebook environment. Typically you do not need to set this but it can be set explicitly (e.x. sagemaker)

• PHOENIX_COLLECTOR_ENDPOINT: The endpoint traces and evals are sent to. This must be set if the Phoenix server is running on a remote instance. For example if phoenix is running at http://125.2.3.5:4040 , this environment variable must be set where your LLM application is running and being traced. Note that the endpoint should not contain trailing slashes or slugs.

• PHOENIX_PROJECT_NAME: The project under which traces will be sent. See projects.

• PHOENIX_CLIENT_HEADERS: The headers to set when talking to the phoenix server. This might be things like authentication headers for hosted phoenix.

FAQs

Permission denied writing to disc

Some phoenix containers run as nonroot and therefore must be granted explicit write permissions to the mounted disc (see https://kubernetes.io/docs/tasks/configure-pod-container/security-context/). Phoenix 4.1.3 and above run as root by default to avoid this. However there are debug and nonroot variants of the image as well.

Persistence using launch_app

While it's not recommended to deploy phoenix via launch_app which is designed to be used only in jupyter notebooks, you can set the use_temp_dir parameter to false to write to the PHOENIX_WORKING_DIR.

Interacting with a deployed instance

If you have deployed a phoenix instance, there is no need to use px.launch_app. Simply set the endpoint parameter in px.Client to the url of your phoenix instance. See Client

Using gRPC for trace collection

Phoenix does natively support gRPC for trace collection post 4.0 release. See for details.