@arizeai/phoenix-client
Version:
A client for the Phoenix API
118 lines (116 loc) • 3.72 kB
JavaScript
import { createClient } from "../client.js";
import { GET_SPANS_FILTERS, GET_SPANS_TRACE_IDS, } from "../constants/serverRequirements.js";
import { resolveProjectIdentifier } from "../types/projects.js";
import { ensureServerCapability } from "../utils/serverVersionUtils.js";
/**
* Get spans from a project with filtering criteria.
*
* This method allows you to search for spans within a project using various filters
* such as time range and supports cursor-based pagination.
* The spans are returned in Phoenix's standard format with human-readable timestamps
* and simplified attribute structures.
*
* @experimental this function is experimental and may change in the future
*
* @param params - The parameters to search for spans
* @returns A paginated response containing spans and optional next cursor
*
* @requires Phoenix server >= 13.9.0 when filtering by `traceIds`
*
* @example
* ```ts
* // Get recent spans from a project
* const result = await getSpans({
* client,
* project: { projectName: "my-project" },
* limit: 50
* });
*
* // Get spans in a time range
* const result = await getSpans({
* client,
* project: { projectName: "my-project" },
* startTime: new Date("2024-01-01"),
* endTime: new Date("2024-01-02"),
* limit: 100
* });
*
* // Get all spans for specific traces (requires Phoenix server >= 13.9.0)
* const result = await getSpans({
* client,
* project: { projectName: "my-project" },
* traceIds: ["trace-abc-123", "trace-def-456"],
* });
*
* // Paginate through results
* let cursor: string | undefined;
* do {
* const result = await getSpans({
* client,
* project: { projectName: "my-project" },
* cursor,
* limit: 100
* });
*
* // Process spans
* result.spans.forEach(span => {
* console.log(`Span: ${span.name}, Trace: ${span.context.trace_id}`);
* });
*
* cursor = result.nextCursor || undefined;
* } while (cursor);
* ```
*/
export async function getSpans({ client: _client, project, cursor, limit = 100, startTime, endTime, traceIds, parentId, name, spanKind, statusCode, }) {
const client = _client ?? createClient();
if (traceIds) {
await ensureServerCapability({ client, requirement: GET_SPANS_TRACE_IDS });
}
if (name != null || spanKind != null || statusCode != null) {
await ensureServerCapability({ client, requirement: GET_SPANS_FILTERS });
}
const projectIdentifier = resolveProjectIdentifier(project);
const params = {
limit,
};
if (cursor) {
params.cursor = cursor;
}
if (startTime) {
params.start_time =
startTime instanceof Date ? startTime.toISOString() : startTime;
}
if (endTime) {
params.end_time = endTime instanceof Date ? endTime.toISOString() : endTime;
}
if (traceIds) {
params.trace_id = traceIds;
}
if (parentId !== undefined) {
params.parent_id = parentId === null ? "null" : parentId;
}
if (name) {
params.name = Array.isArray(name) ? name : [name];
}
if (spanKind) {
params.span_kind = Array.isArray(spanKind) ? spanKind : [spanKind];
}
if (statusCode) {
params.status_code = Array.isArray(statusCode) ? statusCode : [statusCode];
}
const { data, error } = await client.GET("/v1/projects/{project_identifier}/spans", {
params: {
path: {
project_identifier: projectIdentifier,
},
query: params,
},
});
if (error)
throw error;
return {
spans: data?.data ?? [],
nextCursor: data?.next_cursor ?? null,
};
}
//# sourceMappingURL=getSpans.js.map