@arizeai/phoenix-otel 0.0.1 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-otel",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Otel registration and convenience methods",
   "main": "dist/src/index.js",
   "module": "dist/esm/index.js",

package/src/index.ts

@@ -1,2 +1,4 @@
 export { trace } from "@opentelemetry/api";
-export * from "./register";
+export { registerInstrumentations } from "@opentelemetry/instrumentation";
+export { type RegisterParams, register } from "./register";
+export { type Instrumentation } from "@opentelemetry/instrumentation";

package/src/register.ts

@@ -10,15 +10,22 @@ import {
   SpanProcessor,
 } from "@opentelemetry/sdk-trace-node";
 import { getEnvApiKey, getEnvCollectorURL } from "./config";
+import {
+  Instrumentation,
+  registerInstrumentations,
+} from "@opentelemetry/instrumentation";
 
-type RegisterParams = {
+/**
+ * Configuration parameters for registering Phoenix OpenTelemetry tracing
+ */
+export type RegisterParams = {
   /**
    * The project the spans should be associated to
    * @default "default"
    */
   projectName?: string;
   /**
-   * the URL to the phoenix server. Can be postfixed with tracing path.
+   * The URL to the phoenix server. Can be postfixed with tracing path.
    * If not provided, environment variables are checked.
    * @example "https://app.phoenix.arize.com"
    */
@@ -34,20 +41,50 @@ type RegisterParams = {
    * @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.
+   */
+  instrumentations?: Instrumentation[];
   /**
    * Whether to set the tracer as a global provider.
    * @default true
    */
-  setGlobalTracerProvider?: boolean;
+  global?: boolean;
 };
 
+/**
+ * Registers Phoenix OpenTelemetry tracing with the specified configuration
+ *
+ * @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
+ * @returns {NodeTracerProvider} The configured NodeTracerProvider instance
+ *
+ * @example
+ * ```typescript
+ * import { register } from '@arizeai/phoenix-otel';
+ *
+ * const provider = register({
+ *   projectName: 'my-app',
+ *   url: 'https://app.phoenix.arize.com',
+ *   apiKey: 'your-api-key',
+ *   batch: true
+ * });
+ * ```
+ */
 export function register({
   url: paramsUrl,
   apiKey: paramsApiKey,
   projectName = "default",
+  instrumentations,
   batch = true,
-  setGlobalTracerProvider = true,
-}: RegisterParams) {
+  global = true,
+}: RegisterParams): NodeTracerProvider {
   const url = ensureCollectorEndpoint(
     paramsUrl || getEnvCollectorURL() || "http://localhost:6006"
   );
@@ -74,16 +111,24 @@ export function register({
     spanProcessors: [spanProcessor],
   });
 
-  if (setGlobalTracerProvider) {
+  if (instrumentations) {
+    registerInstrumentations({
+      instrumentations,
+      tracerProvider: provider,
+    });
+  }
+  if (global) {
     provider.register();
   }
   return provider;
 }
 
 /**
- * A utility method to normalize the url to be http compatible.
- * Assumes we are using http over gRPC.
- * @param url the url to the phoenix server. May contain a slug
+ * 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.
+ *
+ * @param url - The URL to the phoenix server. May contain a slug
+ * @returns {string} The normalized URL with the '/v1/traces' endpoint
  */
 export function ensureCollectorEndpoint(url: string): string {
   if (!url.includes("/v1/traces")) {