@arizeai/phoenix-client 7.2.0 → 7.3.1

package/src/config.ts

@@ -1,25 +1,24 @@
-import type { EnvironmentConfig } from "@arizeai/phoenix-config";
 import {
   DEFAULT_PHOENIX_BASE_URL,
-  getEnvironmentConfig,
+  getBaseUrlFromEnvironment,
+  getCredentialsFromEnvironment,
 } from "@arizeai/phoenix-config";
 import type { ClientOptions } from "openapi-fetch";
 
 /**
- * Convert a EnvironmentConfig object into a ClientOptions object.
+ * Convert resolved Phoenix credentials into a ClientOptions object.
  *
- * @param environment - The EnvironmentConfig object to convert.
+ * @param credentials - The API key and headers resolved from the environment.
  * @returns The converted ClientOptions object.
  */
-const phoenixEnvironmentToClientOptions = (
-  environment: EnvironmentConfig
+const phoenixCredentialsToClientOptions = (
+  credentials: ReturnType<typeof getCredentialsFromEnvironment>
 ): Partial<ClientOptions> => {
   const options: Partial<ClientOptions> = {
-    baseUrl: environment.PHOENIX_HOST,
     headers: {
-      ...(environment.PHOENIX_CLIENT_HEADERS ?? {}),
-      ...(environment.PHOENIX_API_KEY
-        ? { Authorization: `Bearer ${environment.PHOENIX_API_KEY}` }
+      ...(credentials.headers ?? {}),
+      ...(credentials.apiKey
+        ? { Authorization: `Bearer ${credentials.apiKey}` }
         : {}),
     },
   };
@@ -36,6 +35,17 @@ const phoenixEnvironmentToClientOptions = (
   );
 };
 
+/**
+ * Where a client's base URL came from: an explicit `baseUrl` option
+ * (`"explicit"`), a Phoenix environment variable (`"environment"`), or the
+ * built-in localhost default (`"default"`).
+ *
+ * Explicit configuration outranks the ambient environment, so this is what
+ * decides whether an environment variable may retarget the client's trace
+ * export.
+ */
+export type BaseUrlSource = "default" | "environment" | "explicit";
+
 /**
  * Get the environment options from the environment.
  *
@@ -46,7 +56,14 @@ export const defaultGetEnvironmentOptions = (): Partial<ClientOptions> => {
   if (typeof process !== "object" || typeof process.env !== "object") {
     return {};
   }
-  return phoenixEnvironmentToClientOptions(getEnvironmentConfig());
+  const options = phoenixCredentialsToClientOptions(
+    getCredentialsFromEnvironment()
+  );
+  // The base URL resolves as a tier group (PHOENIX_ENDPOINT first, inferring
+  // from the trace-export variables, then legacy PHOENIX_HOST) rather than
+  // variable by variable.
+  const baseUrl = getBaseUrlFromEnvironment();
+  return baseUrl !== undefined ? { ...options, baseUrl } : options;
 };
 
 /**

package/src/experiments/resumeEvaluation.ts

@@ -31,7 +31,11 @@ import { getExperimentInfo } from "./getExperimentInfo.js";
 import { getExperimentEvaluators } from "./helpers";
 import { getExampleGlobalId } from "./helpers/getExampleGlobalId";
 import { logEvalResumeSummary, PROGRESS_PREFIX } from "./logging";
-import { cleanupOwnedTracerProvider } from "./tracing";
+import {
+  cleanupOwnedTracerProvider,
+  getTraceExportUrl,
+  MISSING_BASE_URL_MESSAGE,
+} from "./tracing";
 
 /**
  * Error thrown when evaluation is aborted due to a failure in stopOnFirstError mode.
@@ -199,14 +203,15 @@ async function handleEvaluationFetchError(
  */
 function setupEvaluationTracer({
   projectName,
-  baseUrl,
+  traceExportUrl,
   headers,
   useBatchSpanProcessor,
   diagLogLevel,
   setGlobalTracerProvider,
 }: {
   projectName: string | null;
-  baseUrl: string;
+  /** Where spans are exported; omit to let `register()` read the environment. */
+  traceExportUrl?: string;
   headers?: Record<string, string>;
   useBatchSpanProcessor: boolean;
   diagLogLevel?: DiagLogLevel;
@@ -222,7 +227,7 @@ function setupEvaluationTracer({
 
   const provider = register({
     projectName,
-    url: baseUrl,
+    url: traceExportUrl,
     headers,
     batch: useBatchSpanProcessor,
     diagLogLevel,
@@ -323,14 +328,11 @@ export async function resumeEvaluation({
 
   // Initialize tracer (only if experiment has a project_name)
   const baseUrl = client.config.baseUrl;
-  invariant(
-    baseUrl,
-    "Phoenix base URL not found. Please set PHOENIX_HOST or set baseUrl on the client."
-  );
+  invariant(baseUrl, MISSING_BASE_URL_MESSAGE);
 
   const tracerSetup = setupEvaluationTracer({
     projectName: experiment.projectName,
-    baseUrl,
+    traceExportUrl: getTraceExportUrl(client.config),
     headers: client.config.headers
       ? toObjectHeaders(client.config.headers)
       : undefined,

package/src/experiments/resumeExperiment.ts

@@ -35,7 +35,11 @@ import {
   PROGRESS_PREFIX,
 } from "./logging";
 import { resumeEvaluation } from "./resumeEvaluation";
-import { cleanupOwnedTracerProvider } from "./tracing";
+import {
+  cleanupOwnedTracerProvider,
+  getTraceExportUrl,
+  MISSING_BASE_URL_MESSAGE,
+} from "./tracing";
 
 /**
  * Error thrown when task is aborted due to a failure in stopOnFirstError mode.
@@ -182,14 +186,15 @@ async function handleFetchError(
  */
 function setupTracer({
   projectName,
-  baseUrl,
+  traceExportUrl,
   headers,
   useBatchSpanProcessor,
   diagLogLevel,
   setGlobalTracerProvider,
 }: {
   projectName: string | null;
-  baseUrl: string;
+  /** Where spans are exported; omit to let `register()` read the environment. */
+  traceExportUrl?: string;
   headers?: Record<string, string>;
   useBatchSpanProcessor: boolean;
   diagLogLevel?: DiagLogLevel;
@@ -205,7 +210,7 @@ function setupTracer({
 
   const provider = register({
     projectName,
-    url: baseUrl,
+    url: traceExportUrl,
     headers,
     batch: useBatchSpanProcessor,
     diagLogLevel,
@@ -307,15 +312,12 @@ export async function resumeExperiment({
 
   // Get base URL for tracing and URL generation
   const baseUrl = client.config.baseUrl;
-  invariant(
-    baseUrl,
-    "Phoenix base URL not found. Please set PHOENIX_HOST or set baseUrl on the client."
-  );
+  invariant(baseUrl, MISSING_BASE_URL_MESSAGE);
 
   // Initialize tracer (only if experiment has a project_name)
   const tracerSetup = setupTracer({
     projectName: experiment.projectName,
-    baseUrl,
+    traceExportUrl: getTraceExportUrl(client.config),
     headers: client.config.headers
       ? toObjectHeaders(client.config.headers)
       : undefined,

package/src/experiments/runExperiment.ts

@@ -54,7 +54,11 @@ import {
   logTaskSummary,
   PROGRESS_PREFIX,
 } from "./logging";
-import { cleanupOwnedTracerProvider } from "./tracing";
+import {
+  cleanupOwnedTracerProvider,
+  getTraceExportUrl,
+  MISSING_BASE_URL_MESSAGE,
+} from "./tracing";
 
 /**
  * Validate that a repetition is valid
@@ -270,14 +274,11 @@ export async function runExperiment({
     };
     // Initialize the tracer, now that we have a project name
     const baseUrl = client.config.baseUrl;
-    invariant(
-      baseUrl,
-      "Phoenix base URL not found. Please set PHOENIX_HOST or set baseUrl on the client."
-    );
+    invariant(baseUrl, MISSING_BASE_URL_MESSAGE);
 
     taskProvider = register({
       projectName,
-      url: baseUrl,
+      url: getTraceExportUrl(client.config),
       headers: client.config.headers
         ? toObjectHeaders(client.config.headers)
         : undefined,
@@ -621,10 +622,7 @@ export async function evaluateExperiment({
   const isDryRun = typeof dryRun === "number" || dryRun === true;
   const client = _client ?? createClient();
   const baseUrl = client.config.baseUrl;
-  invariant(
-    baseUrl,
-    "Phoenix base URL not found. Please set PHOENIX_HOST or set baseUrl on the client."
-  );
+  invariant(baseUrl, MISSING_BASE_URL_MESSAGE);
   let provider: NodeTracerProvider;
   let globalRegistration: GlobalTracerProviderRegistration | null = null;
   const ownsProvider = !paramsTracerProvider;
@@ -635,7 +633,7 @@ export async function evaluateExperiment({
   } else if (!isDryRun) {
     provider = register({
       projectName: "evaluators",
-      url: baseUrl,
+      url: getTraceExportUrl(client.config),
       headers: client.config.headers
         ? toObjectHeaders(client.config.headers)
         : undefined,

package/src/experiments/tracing.ts

@@ -3,6 +3,41 @@ import type {
   NodeTracerProvider,
 } from "@arizeai/phoenix-otel";
 
+import type { BaseUrlSource } from "../config";
+
+/**
+ * Message for the invariant shared by every experiment entry point: a base URL
+ * must be resolvable before a tracer can be registered.
+ */
+export const MISSING_BASE_URL_MESSAGE =
+  "Phoenix base URL not found. Please set PHOENIX_ENDPOINT (or PHOENIX_COLLECTOR_ENDPOINT) or set baseUrl on the client.";
+
+/**
+ * Resolves the URL experiment spans are exported to, as the `url` argument to
+ * `register()`.
+ *
+ * Explicit code-level configuration outranks the ambient environment: a client
+ * created with an explicit `baseUrl` exports its spans to that server, so a
+ * `PHOENIX_COLLECTOR_ENDPOINT` left in the shell cannot silently retarget it.
+ * When the base URL itself came from the environment, so does trace export:
+ * returning `undefined` hands resolution to `register()`, which reads the
+ * trace-export chain (`PHOENIX_COLLECTOR_ENDPOINT`, the OTel-standard
+ * variables, then `PHOENIX_ENDPOINT`) exactly as a standalone `register()`
+ * call would.
+ *
+ * A base URL of unknown provenance — a hand-built client rather than one from
+ * `createClient()` — counts as explicit, since only deliberate configuration
+ * puts a URL there.
+ */
+export function getTraceExportUrl(config: {
+  baseUrl?: string;
+  baseUrlSource?: BaseUrlSource;
+}): string | undefined {
+  return (config.baseUrlSource ?? "explicit") === "explicit"
+    ? config.baseUrl
+    : undefined;
+}
+
 /**
  * Flushes and shuts down a tracer provider that this package created, then
  * detaches any global OTEL registration it owns so another provider can be mounted.

package/src/testing/phoenix-test-tracking.ts

@@ -16,7 +16,10 @@ import {
 import type { Span } from "@opentelemetry/api";
 
 import { createDataset } from "../datasets";
-import { cleanupOwnedTracerProvider } from "../experiments/tracing";
+import {
+  cleanupOwnedTracerProvider,
+  getTraceExportUrl,
+} from "../experiments/tracing";
 import { createClient, type PhoenixClient } from "../index";
 import { ensureString } from "../utils/ensureString";
 import { toObjectHeaders } from "../utils/toObjectHeaders";
@@ -163,9 +166,9 @@ interface TaskSpanLifecycle {
 const taskSpansByRun = new WeakMap<RunState, TaskSpanLifecycle>();
 
 /**
- * Warn once when `PHOENIX_HOST` is plain `http:` while an `Authorization`
- * header is being forwarded to the OTLP exporter — that combination
- * exfiltrates the bearer token in cleartext.
+ * Warn once when the resolved base URL is plain `http:` while an
+ * `Authorization` header is being forwarded to the OTLP exporter — that
+ * combination exfiltrates the bearer token in cleartext.
  */
 let warnedAboutHttpScheme = false;
 function maybeWarnHttpScheme(
@@ -191,9 +194,9 @@ function maybeWarnHttpScheme(
   warnedAboutHttpScheme = true;
   // eslint-disable-next-line no-console
   console.warn(
-    `[@arizeai/phoenix-client] PHOENIX_HOST="${baseUrl}" uses http:// with ` +
-      `an Authorization header set; the bearer token will travel in cleartext. ` +
-      `Use https:// for non-localhost Phoenix endpoints.`
+    `[@arizeai/phoenix-client] The Phoenix base URL "${baseUrl}" uses http:// ` +
+      `with an Authorization header set; the bearer token will travel in ` +
+      `cleartext. Use https:// for non-localhost Phoenix endpoints.`
   );
 }
 
@@ -349,7 +352,7 @@ export async function initializeSuite(suite: SuiteState): Promise<void> {
   if (!baseUrl) {
     suite.trackingDisabled = true;
     suite.setupError = new Error(
-      "Phoenix base URL not found. Set PHOENIX_HOST or pass baseUrl on the client."
+      "Phoenix base URL not found. Set PHOENIX_ENDPOINT (or PHOENIX_COLLECTOR_ENDPOINT) or pass baseUrl on the client."
     );
     suite.tracer = createNoOpProvider().getTracer("no-op");
     suite.evaluatorTracer = suite.tracer;
@@ -362,7 +365,7 @@ export async function initializeSuite(suite: SuiteState): Promise<void> {
   try {
     provider = register({
       projectName: suite.projectName,
-      url: baseUrl,
+      url: getTraceExportUrl(client.config),
       headers: client.config.headers
         ? toObjectHeaders(client.config.headers)
         : undefined,