@arizeai/phoenix-client 6.6.2 → 6.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "6.6.2",
+  "version": "6.7.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",

package/src/__generated__/api/v1.ts

@@ -5149,6 +5149,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 +5220,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

@@ -76,6 +76,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.
  *
@@ -90,5 +98,6 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   ANNOTATE_SESSIONS,
   GET_SPANS_TRACE_IDS,
   GET_SPANS_FILTERS,
+  GET_SPANS_BY_ATTRIBUTE,
   LIST_PROJECT_TRACES,
 ] as const;

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",
     {