@arizeai/phoenix-otel 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-otel",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Otel registration and convenience methods",
   "main": "dist/src/index.js",
   "module": "dist/esm/index.js",
@@ -38,7 +38,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
-    "vitest": "^2.1.9"
+    "vitest": "^4.0.10"
   },
   "scripts": {
     "clean": "rimraf dist",
@@ -46,6 +46,7 @@
     "build": "tsc --build tsconfig.json tsconfig.esm.json && tsc-alias -p tsconfig.esm.json",
     "postbuild": "echo '{\"type\": \"module\"}' > ./dist/esm/package.json",
     "type:check": "tsc --noEmit",
-    "test": "vitest --typecheck"
+    "test": "vitest run",
+    "test:watch": "vitest watch"
   }
 }

package/src/register.ts

@@ -18,93 +18,326 @@ import {
   SpanProcessor,
 } from "@opentelemetry/sdk-trace-node";
 
+/**
+ * Type definition for HTTP headers used in OTLP communication
+ * @example { "custom-header": "value", "x-api-version": "1.0" }
+ */
 export type Headers = Record<string, string>;
 
 /**
- * Configuration parameters for registering Phoenix OpenTelemetry tracing
+ * Configuration parameters for registering Phoenix OpenTelemetry tracing.
+ *
+ * This interface defines all the available options for configuring the Phoenix
+ * OpenTelemetry integration, including connection details, processing options,
+ * and instrumentation settings.
+ *
+ * @example
+ * ```typescript
+ * const config: RegisterParams = {
+ *   projectName: "my-application",
+ *   url: "https://app.phoenix.arize.com",
+ *   apiKey: "your-api-key",
+ *   batch: true,
+ *   global: true
+ * };
+ * ```
  */
 export type RegisterParams = {
   /**
-   * The project the spans should be associated to
+   * The project name that spans will be associated with in Phoenix.
+   * This helps organize and filter traces in the Phoenix UI.
+   *
    * @default "default"
+   * @example "my-web-app"
+   * @example "api-service"
    */
   projectName?: string;
+
   /**
-   * The URL to the phoenix server. Can be postfixed with tracing path.
-   * If not provided, environment variables are checked.
+   * The URL to the Phoenix server. Can be postfixed with the tracing path.
+   * If not provided, the system will check the PHOENIX_COLLECTOR_URL environment variable.
+   *
+   * The URL will be automatically normalized to include the `/v1/traces` endpoint if not present.
+   *
    * @example "https://app.phoenix.arize.com"
+   * @example "https://app.phoenix.arize.com/v1/traces"
+   * @example "http://localhost:6006"
    */
   url?: string;
+
   /**
-   * The API key for the phoenix instance.
-   * If not provided, environment variables are checked.
+   * The API key for authenticating with the Phoenix instance.
+   * If not provided, the system will check the PHOENIX_API_KEY environment variable.
+   *
+   * The API key will be automatically added to the Authorization header as a Bearer token.
+   *
+   * @example "phx_1234567890abcdef"
    */
   apiKey?: string;
+
   /**
-   * Headers to be used when communicating with the OTLP collector
+   * Additional headers to be included when communicating with the OTLP collector.
+   * These headers will be merged with any automatically generated headers (like Authorization).
+   *
+   * @example { "x-custom-header": "value", "x-api-version": "1.0" }
    */
   headers?: Headers;
+
   /**
    * Whether to use batching for span processing.
-   * It is recommended to use batching in production environments
+   *
+   * - `true` (default): Uses OpenInferenceBatchSpanProcessor for better performance in production
+   * - `false`: Uses OpenInferenceSimpleSpanProcessor for immediate span export (useful for debugging)
+   *
+   * Batching is recommended for production environments as it reduces network overhead
+   * and improves performance by sending multiple spans in a single request.
+   *
    * @default true
    */
   batch?: boolean;
+
   /**
-   * A list of instrumentation to register.
-   * Note: this may only work with commonjs projects. ESM projects will require manually applying instrumentation.
+   * A list of OpenTelemetry instrumentations to automatically register.
+   *
+   * **Note**: This feature may only work with CommonJS projects. ESM projects
+   * may require manual instrumentation registration.
+   *
+   * @example
+   * ```typescript
+   * import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+   * import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';
+   *
+   * const instrumentations = [
+   *   new HttpInstrumentation(),
+   *   new ExpressInstrumentation()
+   * ];
+   * ```
    */
   instrumentations?: Instrumentation[];
+
   /**
-   * Whether to set the tracer as a global provider.
+   * Custom span processors to add to the tracer provider.
+   *
+   * **Important**: When provided, this will override the default span processor
+   * created from the `url`, `apiKey`, `headers`, and `batch` parameters.
+   *
+   * @example
+   * ```typescript
+   * import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+   *
+   * const customProcessors = [
+   *   new BatchSpanProcessor(exporter),
+   *   new MyCustomSpanProcessor()
+   * ];
+   * ```
+   */
+  spanProcessors?: SpanProcessor[];
+
+  /**
+   * Whether to register the tracer provider as the global provider.
+   *
+   * When `true` (default), the provider will be registered globally and can be
+   * accessed throughout the application. Set to `false` if you want to manage
+   * the provider lifecycle manually or use multiple providers.
+   *
    * @default true
    */
   global?: boolean;
+
   /**
-   * The diag log level to set for the built in DiagConsoleLogger instance.
-   * Omit to disable built in logging.
+   * The diagnostic log level for the built-in DiagConsoleLogger.
+   *
+   * This controls the verbosity of OpenTelemetry's internal logging.
+   * Omit this parameter to disable built-in logging entirely.
+   *
+   * @example DiagLogLevel.INFO
+   * @example DiagLogLevel.DEBUG
+   * @example DiagLogLevel.ERROR
    */
   diagLogLevel?: DiagLogLevel;
 };
 
 /**
- * Registers Phoenix OpenTelemetry tracing with the specified configuration
+ * Registers Phoenix OpenTelemetry tracing with the specified configuration.
+ *
+ * This function sets up a complete OpenTelemetry tracing pipeline configured
+ * to send traces to a Phoenix instance. It creates a NodeTracerProvider with
+ * appropriate span processors, resource attributes, and optional instrumentations.
+ *
+ * The function handles:
+ * - Creating and configuring a NodeTracerProvider
+ * - Setting up OTLP trace export to Phoenix
+ * - Configuring span processors (batch or simple)
+ * - Registering instrumentations (if provided)
+ * - Setting up resource attributes for project identification
+ * - Optional global provider registration
  *
  * @param params - Configuration parameters for Phoenix tracing
- * @param params.url - The URL to the phoenix server. Can be postfixed with tracing path
- * @param params.apiKey - The API key for the phoenix instance
- * @param params.projectName - The project the spans should be associated to
- * @param params.instrumentations - A list of instrumentation to register
- * @param params.batch - Whether to use batching for span processing
- * @param params.global - Whether to set the tracer as a global provider
- * @param params.diagLogLevel - the diagnostics log level
- * @returns {NodeTracerProvider} The configured NodeTracerProvider instance
+ * @returns The configured NodeTracerProvider instance that can be used to create traces
+ *
+ * @example
+ * Basic usage with minimal configuration:
+ * ```typescript
+ * import { register } from '@arizeai/phoenix-otel';
+ *
+ * // Uses environment variables for URL and API key
+ * const provider = register({
+ *   projectName: 'my-application'
+ * });
+ * ```
+ *
+ * @example
+ * Full configuration with custom settings:
+ * ```typescript
+ * import { register } from '@arizeai/phoenix-otel';
+ * import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+ * import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';
+ *
+ * const provider = register({
+ *   projectName: 'my-web-app',
+ *   url: 'https://app.phoenix.arize.com',
+ *   apiKey: 'phx_1234567890abcdef',
+ *   batch: true,
+ *   global: true,
+ *   instrumentations: [
+ *     new HttpInstrumentation(),
+ *     new ExpressInstrumentation()
+ *   ],
+ *   diagLogLevel: DiagLogLevel.INFO
+ * });
+ * ```
  *
  * @example
+ * Custom span processors:
  * ```typescript
  * import { register } from '@arizeai/phoenix-otel';
+ * import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
+ * import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+ *
+ * const exporter = new OTLPTraceExporter({
+ *   url: 'https://app.phoenix.arize.com/v1/traces',
+ *   headers: { 'Authorization': 'Bearer your-api-key' }
+ * });
  *
  * const provider = register({
  *   projectName: 'my-app',
+ *   spanProcessors: [new BatchSpanProcessor(exporter)],
+ *   global: false // Manual provider management
+ * });
+ * ```
+ *
+ * @example
+ * Debugging configuration:
+ * ```typescript
+ * const provider = register({
+ *   projectName: 'debug-app',
+ *   url: 'http://localhost:6006',
+ *   batch: false, // Immediate span export for debugging
+ *   diagLogLevel: DiagLogLevel.DEBUG
+ * });
+ * ```
+ */
+export function register(params: RegisterParams): NodeTracerProvider {
+  const {
+    projectName = "default",
+    instrumentations,
+    global = true,
+    diagLogLevel,
+    spanProcessors,
+  } = params;
+
+  if (diagLogLevel) {
+    diag.setLogger(new DiagConsoleLogger(), diagLogLevel);
+  }
+  const provider = new NodeTracerProvider({
+    resource: resourceFromAttributes({
+      [SEMRESATTRS_PROJECT_NAME]: projectName,
+    }),
+    spanProcessors: spanProcessors || [getDefaultSpanProcessor(params)],
+  });
+
+  if (instrumentations) {
+    registerInstrumentations({
+      instrumentations,
+      tracerProvider: provider,
+    });
+  }
+  if (global) {
+    provider.register();
+  }
+  return provider;
+}
+/**
+ * Creates a default span processor configured for Phoenix OpenTelemetry tracing.
+ *
+ * This function creates an appropriate span processor (batch or simple) based on
+ * the provided configuration parameters. It handles URL normalization, header
+ * configuration, and API key authentication automatically.
+ *
+ * The function will:
+ * - Normalize the collector URL to include the `/v1/traces` endpoint if needed
+ * - Configure authentication headers using the provided API key
+ * - Merge any additional custom headers
+ * - Create either a batch or simple span processor based on the `batch` parameter
+ *
+ * @param params - Configuration parameters for the span processor
+ * @param params.url - The URL to the Phoenix server (will be normalized to include `/v1/traces`)
+ * @param params.apiKey - The API key for authenticating with the Phoenix instance
+ * @param params.headers - Additional headers to include in OTLP requests
+ * @param params.batch - Whether to use batching for span processing (recommended for production)
+ * @returns A configured SpanProcessor instance ready for use with a NodeTracerProvider
+ *
+ * @example
+ * Basic usage with environment variables:
+ * ```typescript
+ * const processor = getDefaultSpanProcessor({
+ *   batch: true
+ * });
+ * ```
+ *
+ * @example
+ * Full configuration with custom settings:
+ * ```typescript
+ * const processor = getDefaultSpanProcessor({
+ *   url: 'https://app.phoenix.arize.com',
+ *   apiKey: 'phx_1234567890abcdef',
+ *   headers: { 'x-custom-header': 'value' },
+ *   batch: true
+ * });
+ * ```
+ *
+ * @example
+ * Debugging configuration with immediate export:
+ * ```typescript
+ * const processor = getDefaultSpanProcessor({
+ *   url: 'http://localhost:6006',
+ *   batch: false // Immediate span export for debugging
+ * });
+ * ```
+ *
+ * @example
+ * Using with custom headers:
+ * ```typescript
+ * const processor = getDefaultSpanProcessor({
  *   url: 'https://app.phoenix.arize.com',
  *   apiKey: 'your-api-key',
+ *   headers: {
+ *     'x-api-version': '1.0',
+ *     'x-client-name': 'my-app'
+ *   },
  *   batch: true
  * });
  * ```
  */
-export function register({
+export function getDefaultSpanProcessor({
   url: paramsUrl,
   apiKey: paramsApiKey,
   headers: paramsHeaders = {},
-  projectName = "default",
-  instrumentations,
   batch = true,
-  global = true,
-  diagLogLevel,
-}: RegisterParams): NodeTracerProvider {
-  if (diagLogLevel) {
-    diag.setLogger(new DiagConsoleLogger(), diagLogLevel);
-  }
+}: Pick<
+  RegisterParams,
+  "url" | "apiKey" | "batch" | "headers"
+>): SpanProcessor {
   const url = ensureCollectorEndpoint(
     paramsUrl || getEnvCollectorURL() || "http://localhost:6006"
   );
@@ -126,35 +359,70 @@ export function register({
   } else {
     spanProcessor = new OpenInferenceSimpleSpanProcessor({ exporter });
   }
-  const provider = new NodeTracerProvider({
-    resource: resourceFromAttributes({
-      [SEMRESATTRS_PROJECT_NAME]: projectName,
-    }),
-    spanProcessors: [spanProcessor],
-  });
-
-  if (instrumentations) {
-    registerInstrumentations({
-      instrumentations,
-      tracerProvider: provider,
-    });
-  }
-  if (global) {
-    provider.register();
-  }
-  return provider;
+  return spanProcessor;
 }
-
 /**
- * A utility method to normalize the URL to be HTTP compatible.
- * Assumes we are using HTTP over gRPC and ensures the URL ends with the correct traces endpoint.
+ * Normalizes a Phoenix server URL to ensure it includes the correct OTLP traces endpoint.
+ *
+ * This utility function ensures that any Phoenix server URL is properly formatted
+ * to include the `/v1/traces` endpoint required for OTLP trace export. It handles
+ * various URL formats and automatically appends the endpoint if missing.
+ *
+ * The function:
+ * - Checks if the URL already contains `/v1/traces`
+ * - If missing, appends `/v1/traces` to the base URL
+ * - Returns a properly formatted URL string
+ * - Assumes HTTP over gRPC protocol for OTLP communication
  *
- * @param url - The URL to the phoenix server. May contain a slug
- * @returns {string} The normalized URL with the '/v1/traces' endpoint
+ * @param url - The base URL to the Phoenix server (may or may not include the traces endpoint)
+ * @returns A normalized URL string that includes the `/v1/traces` endpoint
+ *
+ * @example
+ * URL without traces endpoint:
+ * ```typescript
+ * const normalized = ensureCollectorEndpoint('https://app.phoenix.arize.com');
+ * // Returns: 'https://app.phoenix.arize.com/v1/traces'
+ * ```
+ *
+ * @example
+ * URL that already includes traces endpoint:
+ * ```typescript
+ * const normalized = ensureCollectorEndpoint('https://app.phoenix.arize.com/v1/traces');
+ * // Returns: 'https://app.phoenix.arize.com/v1/traces'
+ * ```
+ *
+ * @example
+ * Local development URL:
+ * ```typescript
+ * const normalized = ensureCollectorEndpoint('http://localhost:6006');
+ * // Returns: 'http://localhost:6006/v1/traces'
+ * ```
+ *
+ * @example
+ * URL with custom port and path:
+ * ```typescript
+ * const normalized = ensureCollectorEndpoint('https://phoenix.example.com:8080');
+ * // Returns: 'https://phoenix.example.com:8080/v1/traces'
+ * ```
+ *
+ * @example
+ * URL with existing path (edge case):
+ * ```typescript
+ * const normalized = ensureCollectorEndpoint('https://app.phoenix.arize.com/api');
+ * // Returns: 'https://app.phoenix.arize.com/api/v1/traces'
+ * ```
  */
 export function ensureCollectorEndpoint(url: string): string {
   if (!url.includes("/v1/traces")) {
-    return new URL("/v1/traces", url).toString();
+    // Ensure the base URL has a trailing slash for proper path concatenation
+    // Without this, the URL constructor treats the last segment as a file and replaces it
+    const baseUrl = new URL(url);
+    if (!baseUrl.pathname.endsWith("/")) {
+      baseUrl.pathname += "/";
+    }
+    // Append v1/traces to the pathname (without leading slash to append, not replace)
+    baseUrl.pathname += "v1/traces";
+    return baseUrl.toString();
   }
   return new URL(url).toString();
 }