@arizeai/phoenix-client 6.6.2 → 6.8.0

package/docs/span-annotations.mdx

@@ -226,7 +226,7 @@ do {
 
 ## Span Notes
 
-`addSpanNote` attaches a free-text comment to a span. Unlike structured annotations (which are keyed by `name` + `identifier`), notes are append-only — each call creates a new note with a unique timestamp-based identifier, so multiple notes naturally accumulate on the same span.
+`addSpanNote` attaches a free-text comment to a span. Unlike structured annotations (which are keyed by `name` + `identifier`), notes are append-only — each call creates a new note with a unique UUIDv4 identifier, so multiple notes naturally accumulate on the same span.
 
 This makes notes a good mechanism for **open coding**: reviewers can leave qualitative observations on spans during exploratory analysis without needing to define annotation names or scoring rubrics up front. The accumulated notes can later inform what structured annotations to create.
 

package/docs/spans.mdx

@@ -32,6 +32,29 @@ for (const span of result.spans) {
 }
 ```
 
+### Filtering by Attributes
+
+Use the `attributes` parameter to filter spans by OpenInference attribute key-value pairs. Multiple entries are ANDed together. The JS type of the value determines how the stored attribute is matched: a `number` matches a stored integer or float, a `boolean` matches a stored boolean, and a `string` matches a stored string.
+
+```ts
+// Spans from a specific model
+const result = await getSpans({
+  project: { projectName: "support-bot" },
+  attributes: { "llm.model_name": "gpt-4o" },
+});
+
+// Spans for a session and a specific user (AND semantics)
+const result = await getSpans({
+  project: { projectName: "support-bot" },
+  attributes: {
+    "session.id": "sess-abc123",
+    "user.id": "user-42",
+  },
+});
+```
+
+Non-finite number values (`Infinity`, `NaN`) throw a `RangeError`. Requires Phoenix server ≥ 14.9.0.
+
 ## Root Span Queries
 
 Use `parentId: null` to limit results to root spans only.
@@ -45,8 +68,12 @@ const rootSpans = await getSpans({
 
 ## Span Maintenance
 
+### Adding Notes
+
+Use `addSpanNote` to attach a free-text note to a span. Multiple notes can be added to the same span — they are independent entries, each with its own timestamp.
+
 ```ts
-import { addSpanNote, deleteSpan } from "@arizeai/phoenix-client/spans";
+import { addSpanNote } from "@arizeai/phoenix-client/spans";
 
 await addSpanNote({
   spanNote: {
@@ -54,6 +81,12 @@ await addSpanNote({
     note: "Escalated due to failed retrieval",
   },
 });
+```
+
+### Deleting Spans
+
+```ts
+import { deleteSpan } from "@arizeai/phoenix-client/spans";
 
 await deleteSpan({
   spanIdentifier: "abc123def456",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.6.2",
+  "version": "6.8.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -79,8 +79,8 @@
     "openapi-fetch": "^0.12.5",
     "tiny-invariant": "^1.3.3",
     "zod": "^4.0.14",
-    "@arizeai/phoenix-config": "0.1.3",
-    "@arizeai/phoenix-otel": "1.0.0"
+    "@arizeai/phoenix-otel": "1.0.0",
+    "@arizeai/phoenix-config": "0.1.3"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^3.0.29",

package/src/__generated__/api/v1.ts

@@ -458,6 +458,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/trace_notes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create a trace note
+         * @description Add a note annotation to a trace. Notes are special annotations that allow multiple entries per trace (unlike regular annotations which are unique by name and identifier). Each note gets a unique UUIDv4 identifier.
+         */
+        post: operations["createTraceNote"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/traces/{trace_identifier}": {
         parameters: {
             query?: never;
@@ -554,7 +574,7 @@ export interface paths {
         put?: never;
         /**
          * Create a span note
-         * @description Add a note annotation to a span. Notes are special annotations that allow multiple entries per span (unlike regular annotations which are unique by name and identifier). Each note gets a unique timestamp-based identifier.
+         * @description Add a note annotation to a span. Notes are special annotations that allow multiple entries per span (unlike regular annotations which are unique by name and identifier). Each note gets a unique UUIDv4 identifier.
          */
         post: operations["createSpanNote"];
         delete?: never;
@@ -1291,6 +1311,14 @@ export interface components {
              */
             total_queued: number;
         };
+        /** CreateTraceNoteRequestBody */
+        CreateTraceNoteRequestBody: {
+            data: components["schemas"]["TraceNoteData"];
+        };
+        /** CreateTraceNoteResponseBody */
+        CreateTraceNoteResponseBody: {
+            data: components["schemas"]["InsertedTraceAnnotation"];
+        };
         /** CreateUserRequestBody */
         CreateUserRequestBody: {
             /** User */
@@ -3382,6 +3410,19 @@ export interface components {
             /** Spans */
             spans?: components["schemas"]["TraceSpanData"][] | null;
         };
+        /** TraceNoteData */
+        TraceNoteData: {
+            /**
+             * Trace Id
+             * @description OpenTelemetry Trace ID (hex format w/o 0x prefix)
+             */
+            trace_id: string;
+            /**
+             * Note
+             * @description The note text to add to the trace
+             */
+            note: string;
+        };
         /** TraceSpanData */
         TraceSpanData: {
             /** Id */
@@ -5082,6 +5123,57 @@ export interface operations {
             };
         };
     };
+    createTraceNote: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateTraceNoteRequestBody"];
+            };
+        };
+        responses: {
+            /** @description Trace note created successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CreateTraceNoteResponseBody"];
+                };
+            };
+            /** @description Forbidden */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Trace not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "text/plain": string;
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
     deleteTrace: {
         parameters: {
             query?: never;
@@ -5149,6 +5241,8 @@ export interface operations {
                 name?: string[] | null;
                 /** @description Filter by status code(s). Values: OK, ERROR, UNSET */
                 status_code?: string[] | null;
+                /** @description Filter spans by `key:value`. Key is a dot-path (e.g. `user.id`, `metadata.tier`). Value is JSON-parsed: `k:12345` is int, `k:true` is bool, otherwise string (`k:user-42`). To match a numeric- or boolean-looking STRING, JSON-quote it: `user.id:"12345"` (URL-encoded `%2212345%22`). Split is on the first `:` only, so values may contain colons (`session.id:sess:abc:123`, ISO timestamps). Repeat the param to AND filters. List-valued attributes (e.g. `tag.tags`) cannot be matched here. Returns 422 on malformed input (missing colon, empty key/value, or list/dict/null value). */
+                attribute?: string[] | null;
             };
             header?: never;
             path: {
@@ -5218,6 +5312,8 @@ export interface operations {
                 span_kind?: string[] | null;
                 /** @description Filter by status code(s). Values: OK, ERROR, UNSET */
                 status_code?: string[] | null;
+                /** @description Filter spans by `key:value`. Key is a dot-path (e.g. `user.id`, `metadata.tier`). Value is JSON-parsed: `k:12345` is int, `k:true` is bool, otherwise string (`k:user-42`). To match a numeric- or boolean-looking STRING, JSON-quote it: `user.id:"12345"` (URL-encoded `%2212345%22`). Split is on the first `:` only, so values may contain colons (`session.id:sess:abc:123`, ISO timestamps). Repeat the param to AND filters. List-valued attributes (e.g. `tag.tags`) cannot be matched here. Returns 422 on malformed input (missing colon, empty key/value, or list/dict/null value). */
+                attribute?: string[] | null;
             };
             header?: never;
             path: {

package/src/constants/serverRequirements.ts

@@ -53,6 +53,13 @@ export const ANNOTATE_SESSIONS: RouteRequirement = {
   minServerVersion: [12, 0, 0],
 };
 
+export const ADD_TRACE_NOTE: RouteRequirement = {
+  kind: "route",
+  method: "POST",
+  path: "/v1/trace_notes",
+  minServerVersion: [14, 13, 0],
+};
+
 export const GET_SPANS_TRACE_IDS: ParameterRequirement = {
   kind: "parameter",
   parameterName: "trace_id",
@@ -76,6 +83,14 @@ export const LIST_PROJECT_TRACES: RouteRequirement = {
   minServerVersion: [13, 15, 0],
 };
 
+export const GET_SPANS_BY_ATTRIBUTE: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "attribute",
+  parameterLocation: "query",
+  route: "GET /v1/projects/{id}/spans",
+  minServerVersion: [14, 9, 0],
+};
+
 /**
  * Aggregate list of every known capability requirement.
  *
@@ -88,7 +103,9 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   DELETE_SESSIONS,
   LIST_PROJECT_SESSIONS,
   ANNOTATE_SESSIONS,
+  ADD_TRACE_NOTE,
   GET_SPANS_TRACE_IDS,
   GET_SPANS_FILTERS,
+  GET_SPANS_BY_ATTRIBUTE,
   LIST_PROJECT_TRACES,
 ] as const;

package/src/spans/addSpanNote.ts

@@ -27,7 +27,7 @@ export interface AddSpanNoteParams extends ClientFn {
  *
  * Notes are a special type of annotation that allow multiple entries per span
  * (unlike regular annotations which are unique by name and identifier).
- * Each note gets a unique timestamp-based identifier.
+ * Each note gets a unique UUIDv4 identifier.
  *
  * @param params - The parameters to add a span note
  * @returns The ID of the created note annotation

package/src/spans/getSpans.ts

@@ -1,6 +1,7 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
 import {
+  GET_SPANS_BY_ATTRIBUTE,
   GET_SPANS_FILTERS,
   GET_SPANS_TRACE_IDS,
 } from "../constants/serverRequirements";
@@ -10,6 +11,38 @@ import { resolveProjectIdentifier } from "../types/projects";
 import type { SpanKindFilter, SpanStatusCode } from "../types/spans";
 import { ensureServerCapability } from "../utils/serverVersionUtils";
 
+export type SpanAttributeValue = string | number | boolean;
+export type SpanAttributes = Record<string, SpanAttributeValue>;
+
+function serializeAttributeValue(value: SpanAttributeValue): string {
+  if (typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new RangeError(
+        `Non-finite attribute filter values are not supported: ${value}`
+      );
+    }
+    return String(value);
+  }
+  if (value === "") {
+    return JSON.stringify(value);
+  }
+  try {
+    const parsed = JSON.parse(value);
+    return typeof parsed === "string" ? value : JSON.stringify(value);
+  } catch {
+    return value;
+  }
+}
+
+function serializeAttributes(attributes: SpanAttributes): string[] {
+  return Object.entries(attributes).map(
+    ([key, value]) => `${key}:${serializeAttributeValue(value)}`
+  );
+}
+
 /**
  * Parameters to get spans from a project using auto-generated types
  */
@@ -34,6 +67,12 @@ export interface GetSpansParams extends ClientFn {
   spanKind?: SpanKindFilter | SpanKindFilter[] | null;
   /** Filter by status code(s) (OK, ERROR, UNSET) */
   statusCode?: SpanStatusCode | SpanStatusCode[] | null;
+  /**
+   * Filter by attribute key/value pairs with AND semantics. The value's JS type
+   * selects how the stored attribute is matched: `{ "user.id": 12345 }` matches
+   * a stored integer, while `{ "user.id": "12345" }` matches a stored string.
+   */
+  attributes?: SpanAttributes | null;
 }
 
 export type GetSpansResponse = operations["getSpans"]["responses"]["200"];
@@ -57,6 +96,7 @@ export type GetSpansResult = {
  * @returns A paginated response containing spans and optional next cursor
  *
  * @requires Phoenix server >= 13.9.0 when filtering by `traceIds`
+ * @requires Phoenix server >= 14.9.0 when filtering by `attributes`
  *
  * @example
  * ```ts
@@ -116,14 +156,27 @@ export async function getSpans({
   name,
   spanKind,
   statusCode,
+  attributes,
 }: GetSpansParams): Promise<GetSpansResult> {
   const client = _client ?? createClient();
+  const serializedAttributes =
+    attributes != null ? serializeAttributes(attributes) : undefined;
+  const attributeFilters =
+    serializedAttributes != null && serializedAttributes.length > 0
+      ? serializedAttributes
+      : undefined;
   if (traceIds) {
     await ensureServerCapability({ client, requirement: GET_SPANS_TRACE_IDS });
   }
   if (name != null || spanKind != null || statusCode != null) {
     await ensureServerCapability({ client, requirement: GET_SPANS_FILTERS });
   }
+  if (attributeFilters != null) {
+    await ensureServerCapability({
+      client,
+      requirement: GET_SPANS_BY_ATTRIBUTE,
+    });
+  }
   const projectIdentifier = resolveProjectIdentifier(project);
 
   const params: NonNullable<operations["getSpans"]["parameters"]["query"]> = {
@@ -163,6 +216,10 @@ export async function getSpans({
     params.status_code = Array.isArray(statusCode) ? statusCode : [statusCode];
   }
 
+  if (attributeFilters != null) {
+    params.attribute = attributeFilters;
+  }
+
   const { data, error } = await client.GET(
     "/v1/projects/{project_identifier}/spans",
     {

package/src/traces/addTraceNote.ts

@@ -0,0 +1,71 @@
+import { createClient } from "../client";
+import { ADD_TRACE_NOTE } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for a single trace note.
+ */
+export interface TraceNote {
+  /**
+   * The OpenTelemetry trace ID (hex format without 0x prefix).
+   */
+  traceId: string;
+  /**
+   * The note text to add to the trace.
+   */
+  note: string;
+}
+
+/**
+ * Parameters to add a trace note.
+ */
+export interface AddTraceNoteParams extends ClientFn {
+  traceNote: TraceNote;
+}
+
+/**
+ * Add a note to a trace.
+ *
+ * Notes are a special type of annotation that allow multiple entries per trace.
+ * Each note gets a unique timestamp-based identifier.
+ *
+ * @param params - The parameters to add a trace note.
+ * @returns The ID of the created note annotation.
+ *
+ * @example
+ * ```ts
+ * const result = await addTraceNote({
+ *   traceNote: {
+ *     traceId: "abc123",
+ *     note: "Needs review"
+ *   }
+ * });
+ * ```
+ */
+export async function addTraceNote({
+  client: _client,
+  traceNote,
+}: AddTraceNoteParams): Promise<{ id: string }> {
+  const client = _client ?? createClient();
+  await ensureServerCapability({ client, requirement: ADD_TRACE_NOTE });
+
+  const { data, error } = await client.POST("/v1/trace_notes", {
+    body: {
+      data: {
+        trace_id: traceNote.traceId.trim(),
+        note: traceNote.note,
+      },
+    },
+  });
+
+  if (error) {
+    throw new Error(`Failed to add trace note: ${error}`);
+  }
+
+  if (!data?.data) {
+    throw new Error("Failed to add trace note: no data returned");
+  }
+
+  return data.data;
+}

package/src/traces/index.ts

@@ -1 +1,2 @@
+export * from "./addTraceNote";
 export * from "./getTraces";