feat: add request tracing and documentation (#495)

* feat: add request tracing  and documentation

- Introduced Request Tracing feature to track and debug API requests using trace IDs.
- Updated documentation in advanced features, client configuration, and troubleshooting sections to include usage examples and details about trace ID formats.
- Added support for automatic timestamp (`client-request-unixmsec`) in requests.
- Enhanced gRPC client to handle trace IDs in metadata.
- Updated tests to validate trace ID functionality in various API calls.

Signed-off-by: ryjiang <jiangruiyi@gmail.com>

* refactor: improve client request ID handling in metadata

- Extracted client request ID logic into a separate function for better readability and maintainability.
- Updated the `promisify` and `extractRequestMetadata` functions to utilize the new `getClientRequestId` function.
- Removed redundant `Math.floor()` call in `currentTimeMs` function.

Signed-off-by: ryjiang <jiangruiyi@gmail.com>

---------

Signed-off-by: ryjiang <jiangruiyi@gmail.com>

Author: shanghaikid

docs/content/advanced/advanced-features.mdx

@@ -124,6 +124,103 @@ const client = new MilvusClient({
 });
 ```
 
+## Request Tracing (TraceID)
+
+Track and trace individual requests using trace IDs for debugging and monitoring purposes.
+
+### Overview
+
+The SDK automatically adds a timestamp (`client-request-unixmsec`) to every request. You can optionally provide a `client_request_id` (or `client-request-id`) to track specific requests across your application.
+
+### Automatic Timestamp
+
+Every request automatically includes a `client-request-unixmsec` timestamp:
+
+```javascript
+// This request will have client-request-unixmsec automatically added
+await client.createCollection({
+  collection_name: 'my_collection',
+  fields: [...],
+  // Timestamp is added automatically, no configuration needed
+});
+```
+
+### Using TraceID
+
+Add a trace ID to track specific requests:
+
+```javascript
+// Recommended: use client_request_id (JavaScript/TypeScript convention)
+const traceId = `trace-${Date.now()}`;
+await client.createCollection({
+  collection_name: 'my_collection',
+  fields: [...],
+  client_request_id: traceId,
+});
+
+// Alternative: use client-request-id (compatible with pymilvus)
+await client.createCollection({
+  collection_name: 'my_collection',
+  fields: [...],
+  'client-request-id': traceId,
+});
+```
+
+**Note**: If both formats are provided, `client_request_id` takes priority (JavaScript/TypeScript convention).
+
+### Supported Operations
+
+All API methods that extend `GrpcTimeOut` support trace IDs:
+
+```javascript
+// Insert with trace ID
+await client.insert({
+  collection_name: 'my_collection',
+  data: [
+    { id: 1, vector: [0.1, 0.2, 0.3] },
+  ],
+  client_request_id: 'insert-trace-123',
+});
+
+// Search with trace ID
+await client.search({
+  collection_name: 'my_collection',
+  vector: [0.1, 0.2, 0.3],
+  limit: 10,
+  client_request_id: 'search-trace-456',
+});
+
+// Query with trace ID
+await client.query({
+  collection_name: 'my_collection',
+  expr: 'id > 100',
+  client_request_id: 'query-trace-789',
+});
+
+// All other operations support trace IDs
+await client.createIndex({
+  collection_name: 'my_collection',
+  field_name: 'vector',
+  index_type: 'IVF_FLAT',
+  client_request_id: 'index-trace-101',
+});
+```
+
+### Use Cases
+
+1. **Request Tracking**: Track requests across distributed systems
+2. **Debugging**: Identify specific requests in logs
+3. **Performance Monitoring**: Correlate trace IDs with performance metrics
+4. **Error Investigation**: Trace errors back to specific requests
+
+### Implementation Details
+
+- Trace IDs are passed through gRPC metadata
+- Both `client_request_id` and `client-request-id` formats are supported
+- Trace IDs are automatically extracted from request parameters
+- The timestamp `client-request-unixmsec` is automatically added by the interceptor
+- No need to modify API method implementations
+
 ## Iterator Patterns
 
 ### Query Iterator

docs/content/core-concepts/client-configuration.mdx

@@ -286,6 +286,34 @@ interface ClientConfig {
 }
 ```
 
+## Request Tracing
+
+All API requests support optional trace IDs for tracking and debugging:
+
+```javascript
+// Add trace ID to any request
+await client.createCollection({
+  collection_name: 'my_collection',
+  fields: [...],
+  client_request_id: 'trace-id-123', // Optional trace ID
+});
+
+// Alternative format (compatible with pymilvus)
+await client.createCollection({
+  collection_name: 'my_collection',
+  fields: [...],
+  'client-request-id': 'trace-id-123',
+});
+```
+
+**Features:**
+- Automatic timestamp: Every request includes `client-request-unixmsec`
+- Trace ID support: Add `client_request_id` or `client-request-id` to track requests
+- Global support: All API methods automatically support trace IDs
+- Priority: `client_request_id` takes priority over `client-request-id` (JavaScript convention)
+
+For more details, see [Request Tracing](../advanced/advanced-features#request-tracing-traceid) in Advanced Features.
+
 ## Next Steps
 
 - Learn about [Data Types & Schemas](./data-types-schemas)

docs/content/reference/troubleshooting.mdx

@@ -255,6 +255,28 @@ const client = new MilvusClient({
 });
 ```
 
+### Use TraceID for Request Tracking
+
+Add trace IDs to track specific requests:
+
+```javascript
+// Add trace ID to track requests
+await client.createCollection({
+  collection_name: 'my_collection',
+  fields: [...],
+  client_request_id: 'debug-trace-123', // Track this specific request
+});
+
+// All operations support trace IDs
+await client.insert({
+  collection_name: 'my_collection',
+  data: [...],
+  client_request_id: 'insert-trace-456',
+});
+```
+
+This helps correlate logs and errors with specific requests. See [Request Tracing](../advanced/advanced-features#request-tracing-traceid) for more details.
+
 ### Check Collection Schema
 
 ```javascript

milvus/const/client.ts

@@ -2,6 +2,8 @@ export enum METADATA {
   DATABASE = 'dbname',
   AUTH = 'authorization',
   CLIENT_ID = 'identifier',
+  CLIENT_REQUEST_ID = 'client-request-id',
+  CLIENT_REQUEST_UNIXMSEC = 'client-request-unixmsec',
 }
 
 export enum CONNECT_STATUS {

milvus/grpc/Collection.ts

@@ -201,6 +201,7 @@ export class Collection extends Database {
     }
 
     // Call the promisify function to create the collection.
+    // traceid will be automatically extracted from data by promisify
     const createPromise = await promisify(
       this.channelPool,
       'CreateCollection',

milvus/grpc/GrpcClient.ts

@@ -18,6 +18,7 @@ import {
   getRetryInterceptor,
   getMetaInterceptor,
   getTraceInterceptor,
+  getRequestMetadataInterceptor,
   ErrorCode,
   DEFAULT_DB,
   METADATA,
@@ -100,6 +101,9 @@ export class GRPCClient extends User {
     // interceptors
     const interceptors = [metaInterceptor];
 
+    // add request metadata interceptor (adds client-request-unixmsec)
+    interceptors.push(getRequestMetadataInterceptor());
+
     // add trace if necessary
     if (this.config.trace) {
       // add trace interceptor

milvus/types/Common.ts

@@ -32,6 +32,8 @@ export interface StringArrayId {
 }
 export interface GrpcTimeOut {
   timeout?: number;
+  client_request_id?: string; // optional, trace id for request tracking
+  'client-request-id'?: string; // optional, trace id for request tracking (alternative format)
 }
 export type PrivilegesTypes =
   | CollectionPrivileges

milvus/utils/Function.ts

@@ -1,56 +1,77 @@
 import {
   KeyValuePair,
-  DataType,
-  ERROR_REASONS,
   FieldSchema,
   DataTypeStringEnum,
   DEFAULT_MIN_INT64,
   SparseFloatVector,
   FieldData,
-  FieldType,
+  METADATA,
 } from '../';
 import { Pool } from 'generic-pool';
+import { Metadata } from '@grpc/grpc-js';
 
 /**
- * Promisify a function call with optional timeout
- * @param obj - The object containing the target function
+ * Promisify a function call with optional timeout and metadata
+ * @param pool - The pool of gRPC clients
  * @param target - The name of the target function to call
- * @param params - The parameters to pass to the target function
+ * @param params - The parameters to pass to the target function (may contain client_request_id or client-request-id)
  * @param timeout - Optional timeout in milliseconds
+ * @param requestMetadata - Optional metadata to include in the request (e.g., client-request-id). If not provided, will be extracted from params automatically.
  * @returns A Promise that resolves with the result of the target function call
  */
 export async function promisify(
   pool: Pool<any>,
   target: string,
   params: any,
-  timeout: number
+  timeout: number,
+  requestMetadata?: { 'client-request-id'?: string; client_request_id?: string }
 ): Promise<any> {
   // Calculate the deadline for the function call
   const t = timeout === 0 ? 1000 * 60 * 60 * 24 : timeout;
 
   // get client
   const client = await pool.acquire();
 
+  // Extract traceid from params if requestMetadata is not explicitly provided
+  let finalRequestMetadata = requestMetadata;
+  if (!finalRequestMetadata && params) {
+    finalRequestMetadata = extractRequestMetadata(params);
+  }
+
+  // Create metadata object if traceid is found
+  const metadata = finalRequestMetadata ? new Metadata() : undefined;
+
+  if (metadata && finalRequestMetadata) {
+    // Support both client_request_id and client-request-id (for compatibility)
+    // Priority: client_request_id > client-request-id (JavaScript/TypeScript convention)
+    const clientRequestId = getClientRequestId(finalRequestMetadata);
+    if (clientRequestId) {
+      // Convert to string to prevent runtime errors if non-string value is passed
+      metadata.add(METADATA.CLIENT_REQUEST_ID, String(clientRequestId));
+    }
+  }
+
   // Create a new Promise that wraps the target function call
   return new Promise((resolve, reject) => {
     try {
-      // Call the target function with the provided parameters and deadline
-      client[target](
-        params,
-        { deadline: new Date(Date.now() + t) },
-        (err: any, result: any) => {
-          if (err) {
-            // If there was an error, reject the Promise with the error
-            reject(err);
-          } else {
-            // Otherwise, resolve the Promise with the result
-            resolve(result);
-          }
-          if (client) {
-            pool.release(client);
-          }
+      // Call the target function with the provided parameters, deadline, and metadata
+      const callOptions: any = { deadline: new Date(Date.now() + t) };
+      if (metadata) {
+        callOptions.metadata = metadata;
+      }
+
+      client[target](params, callOptions, (err: any, result: any) => {
+        if (err) {
+          // If there was an error, reject the Promise with the error
+          reject(err);
+        } else {
+          // Otherwise, resolve the Promise with the result
+          resolve(result);
         }
-      );
+        if (client) {
+          pool.release(client);
+        }
+      });
     } catch (e: any) {
       reject(e);
       if (client) {
@@ -139,3 +160,40 @@ export const getValidDataArray = (data: FieldData[], length: number) => {
     return data[i] !== undefined && data[i] !== null;
   });
 };
+
+/**
+ * Extracts client request ID from metadata object with priority handling.
+ * Priority: client_request_id > client-request-id (JavaScript/TypeScript convention)
+ * @param metadata - Metadata object that may contain traceid
+ * @returns Client request ID as string or undefined if not found
+ */
+const getClientRequestId = (metadata?: {
+  'client-request-id'?: string;
+  client_request_id?: string;
+}): string | undefined => {
+  if (!metadata) {
+    return undefined;
+  }
+  // Priority: client_request_id > client-request-id (JavaScript/TypeScript convention)
+  return metadata.client_request_id || metadata['client-request-id'];
+};
+
+/**
+ * Extracts request metadata (traceid) from request data.
+ * Supports both client_request_id and client-request-id formats.
+ * Priority: client_request_id > client-request-id (JavaScript/TypeScript convention)
+ * @param data - Request data that may contain traceid
+ * @returns Request metadata object or undefined if no traceid provided
+ */
+export const extractRequestMetadata = (
+  data: any
+):
+  | {
+      'client-request-id': string;
+    }
+  | undefined => {
+  const clientRequestId = getClientRequestId(data);
+  return clientRequestId
+    ? { 'client-request-id': String(clientRequestId) }
+    : undefined;
+};

milvus/utils/Grpc.ts

@@ -19,7 +19,7 @@ interface Carrier {
   traceparent?: string;
   tracestate?: string;
 }
-import { DEFAULT_DB } from '../const';
+import { DEFAULT_DB, METADATA } from '../const';
 import sdkInfo from '../../sdk.json';
 import milvusProtoJson from '../proto-json/milvus';
 import { INamespace } from 'protobufjs';
@@ -256,6 +256,36 @@ export const getRetryInterceptor = ({
     return new InterceptingCall(nextCall(options), requester);
   };
 
+/**
+ * Returns current time in milliseconds as a string.
+ * @returns Current time in milliseconds as a string.
+ */
+const currentTimeMs = (): string => {
+  // Date.now() already returns an integer, so Math.floor() is redundant
+  return String(Date.now());
+};
+
+/**
+ * Returns a gRPC interceptor function that adds request-level metadata to outgoing requests.
+ * This interceptor automatically adds client-request-unixmsec timestamp to every request.
+ * The client-request-id should be passed via promisify's requestMetadata parameter.
+ */
+export const getRequestMetadataInterceptor = () => {
+  return function (options: any, nextCall: any) {
+    // Create a new InterceptingCall object with nextCall(options) as its first parameter.
+    return new InterceptingCall(nextCall(options), {
+      // Define the start method of the InterceptingCall object.
+      start: function (metadata, listener, next) {
+        // Always add client-request-unixmsec timestamp
+        metadata.add(METADATA.CLIENT_REQUEST_UNIXMSEC, currentTimeMs());
+
+        // Call next(metadata, listener) to continue the call with the modified metadata.
+        next(metadata, listener);
+      },
+    });
+  };
+};
+
 /**
  * Returns a gRPC interceptor function that adds trace context to outgoing requests.
  */