@arizeai/phoenix-otel 0.2.1 → 0.3.1

package/dist/src/register.d.ts

@@ -1,85 +1,329 @@
-import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import { Instrumentation } from "@opentelemetry/instrumentation";
 import { DiagLogLevel } from "@opentelemetry/api";
+import { Instrumentation } from "@opentelemetry/instrumentation";
+import { NodeTracerProvider, 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 declare function register(params: RegisterParams): NodeTracerProvider;
+/**
+ * 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 declare function register({ url: paramsUrl, apiKey: paramsApiKey, headers: paramsHeaders, projectName, instrumentations, batch, global, diagLogLevel, }: RegisterParams): NodeTracerProvider;
+export declare function getDefaultSpanProcessor({ url: paramsUrl, apiKey: paramsApiKey, headers: paramsHeaders, batch, }: Pick<RegisterParams, "url" | "apiKey" | "batch" | "headers">): 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.
  *
- * @param url - The URL to the phoenix server. May contain a slug
- * @returns {string} The normalized URL with the '/v1/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 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 declare function ensureCollectorEndpoint(url: string): string;
 //# sourceMappingURL=register.d.ts.map

package/dist/src/register.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/register.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,kBAAkB,EAEnB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,eAAe,EAEhB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAA2B,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE3E,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,aAAkB,EAC3B,WAAuB,EACvB,gBAAgB,EAChB,KAAY,EACZ,MAAa,EACb,YAAY,GACb,EAAE,cAAc,GAAG,kBAAkB,CA0CrC;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK3D"}
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/register.ts"],"names":[],"mappings":"AAQA,OAAO,EAA2B,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EACL,eAAe,EAEhB,MAAM,gCAAgC,CAAC;AAExC,OAAO,EACL,kBAAkB,EAClB,aAAa,EACd,MAAM,+BAA+B,CAAC;AAEvC;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;;;;;;OASG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;;;OAUG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,CAAC,EAAE,eAAe,EAAE,CAAC;IAErC;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IAEjC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,kBAAkB,CA6BnE;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,aAAkB,EAC3B,KAAY,GACb,EAAE,IAAI,CACL,cAAc,EACd,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CACvC,GAAG,aAAa,CAuBhB;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAa3D"}

package/dist/src/register.js

@@ -1,44 +1,181 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.register = register;
+exports.getDefaultSpanProcessor = getDefaultSpanProcessor;
 exports.ensureCollectorEndpoint = ensureCollectorEndpoint;
 const openinference_semantic_conventions_1 = require("@arizeai/openinference-semantic-conventions");
 const openinference_vercel_1 = require("@arizeai/openinference-vercel");
+const config_1 = require("./config");
+const api_1 = require("@opentelemetry/api");
 const exporter_trace_otlp_proto_1 = require("@opentelemetry/exporter-trace-otlp-proto");
+const instrumentation_1 = require("@opentelemetry/instrumentation");
 const resources_1 = require("@opentelemetry/resources");
 const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
-const config_1 = require("./config");
-const instrumentation_1 = require("@opentelemetry/instrumentation");
-const api_1 = require("@opentelemetry/api");
 /**
- * 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-app',
+ *   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: 'your-api-key',
- *   batch: true
+ *   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
  * });
  * ```
  */
-function register({ url: paramsUrl, apiKey: paramsApiKey, headers: paramsHeaders = {}, projectName = "default", instrumentations, batch = true, global = true, diagLogLevel, }) {
+function register(params) {
+    const { projectName = "default", instrumentations, global = true, diagLogLevel, spanProcessors, } = params;
     if (diagLogLevel) {
         api_1.diag.setLogger(new api_1.DiagConsoleLogger(), diagLogLevel);
     }
+    const provider = new sdk_trace_node_1.NodeTracerProvider({
+        resource: (0, resources_1.resourceFromAttributes)({
+            [openinference_semantic_conventions_1.SEMRESATTRS_PROJECT_NAME]: projectName,
+        }),
+        spanProcessors: spanProcessors || [getDefaultSpanProcessor(params)],
+    });
+    if (instrumentations) {
+        (0, instrumentation_1.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
+ * });
+ * ```
+ */
+function getDefaultSpanProcessor({ url: paramsUrl, apiKey: paramsApiKey, headers: paramsHeaders = {}, batch = true, }) {
     const url = ensureCollectorEndpoint(paramsUrl || (0, config_1.getEnvCollectorURL)() || "http://localhost:6006");
     const apiKey = paramsApiKey || (0, config_1.getEnvApiKey)();
     const headers = Array.isArray(paramsHeaders)
@@ -59,33 +196,70 @@ function register({ url: paramsUrl, apiKey: paramsApiKey, headers: paramsHeaders
     else {
         spanProcessor = new openinference_vercel_1.OpenInferenceSimpleSpanProcessor({ exporter });
     }
-    const provider = new sdk_trace_node_1.NodeTracerProvider({
-        resource: (0, resources_1.resourceFromAttributes)({
-            [openinference_semantic_conventions_1.SEMRESATTRS_PROJECT_NAME]: projectName,
-        }),
-        spanProcessors: [spanProcessor],
-    });
-    if (instrumentations) {
-        (0, instrumentation_1.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 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'
+ * ```
  *
- * @param url - The URL to the phoenix server. May contain a slug
- * @returns {string} The normalized URL with the '/v1/traces' endpoint
+ * @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'
+ * ```
  */
 function ensureCollectorEndpoint(url) {
     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();
 }

package/dist/src/register.js.map

@@ -1 +1 @@
-{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/register.ts"],"names":[],"mappings":";;AA4FA,4BAmDC;AASD,0DAKC;AA7JD,oGAAuF;AACvF,wEAGuC;AACvC,wFAA6E;AAC7E,wDAAkE;AAClE,kEAGuC;AACvC,qCAA4D;AAC5D,oEAGwC;AACxC,4CAA2E;AAmD3E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAgB,QAAQ,CAAC,EACvB,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,aAAa,GAAG,EAAE,EAC3B,WAAW,GAAG,SAAS,EACvB,gBAAgB,EAChB,KAAK,GAAG,IAAI,EACZ,MAAM,GAAG,IAAI,EACb,YAAY,GACG;IACf,IAAI,YAAY,EAAE,CAAC;QACjB,UAAI,CAAC,SAAS,CAAC,IAAI,uBAAiB,EAAE,EAAE,YAAY,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,GAAG,GAAG,uBAAuB,CACjC,SAAS,IAAI,IAAA,2BAAkB,GAAE,IAAI,uBAAuB,CAC7D,CAAC;IACF,MAAM,MAAM,GAAG,YAAY,IAAI,IAAA,qBAAY,GAAE,CAAC;IAC9C,MAAM,OAAO,GAAY,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC;QACnD,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC;QACnC,CAAC,CAAC,aAAa,CAAC;IAClB,MAAM,gBAAgB,GAAG,OAAO,MAAM,IAAI,QAAQ,CAAC;IACnD,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,MAAM,EAAE,CAAC;IAChD,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,6CAAiB,CAAC;QACrC,GAAG;QACH,OAAO;KACR,CAAC,CAAC;IACH,IAAI,aAA4B,CAAC;IACjC,IAAI,KAAK,EAAE,CAAC;QACV,aAAa,GAAG,IAAI,sDAA+B,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;IACpE,CAAC;SAAM,CAAC;QACN,aAAa,GAAG,IAAI,uDAAgC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,mCAAkB,CAAC;QACtC,QAAQ,EAAE,IAAA,kCAAsB,EAAC;YAC/B,CAAC,6DAAwB,CAAC,EAAE,WAAW;SACxC,CAAC;QACF,cAAc,EAAE,CAAC,aAAa,CAAC;KAChC,CAAC,CAAC;IAEH,IAAI,gBAAgB,EAAE,CAAC;QACrB,IAAA,0CAAwB,EAAC;YACvB,gBAAgB;YAChB,cAAc,EAAE,QAAQ;SACzB,CAAC,CAAC;IACL,CAAC;IACD,IAAI,MAAM,EAAE,CAAC;QACX,QAAQ,CAAC,QAAQ,EAAE,CAAC;IACtB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,uBAAuB,CAAC,GAAW;IACjD,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QAChC,OAAO,IAAI,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;AACjC,CAAC"}
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/register.ts"],"names":[],"mappings":"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"}