autotel-mongoose 8.0.0 → 8.1.0

package/README.md

@@ -77,6 +77,117 @@ userSchema.pre('save', async function () {
 });
 ```
 
+## Custom Statics, Methods & Query Helpers
+
+The functions you add via `schema.statics`, `schema.methods`, and `schema.query`
+are invisible to the built-in Model/Query instrumentation. This package traces
+them automatically — **no manual `trace()` calls** and no behavioral side
+effects (same `this`, same return value, same error propagation). Each call
+gets an `INTERNAL` span named `mongoose.<Model>.<fn>`.
+
+```typescript
+userSchema.statics.findByEmail = function (email: string) {
+  return this.findOne({ email }); // span: mongoose.User.findByEmail
+};
+
+userSchema.methods.describe = function () {
+  return `${this.name} <${this.email}>`; // span: mongoose.User.describe
+};
+
+userSchema.query.byEmailDomain = function (domain: string) {
+  return this.where({ email: new RegExp(`@${domain}$`) }); // span: mongoose.User.byEmailDomain
+};
+```
+
+Example spans (from `apps/example-mongoose`, debug output). Note that a static
+returning a Query becomes the **parent** of the underlying operation span, and
+parameters are redacted by default:
+
+```text
+✓ findOne users                           1ms [autotel-mongoose]
+     db.system.name=mongodb, db.operation.name=findOne, db.collection.name=users, db.query.text={"condition":{"email":"A***@***.com"},...
+✓ mongoose.User.findByEmail               2ms [autotel-mongoose]
+     db.system.name=mongodb, code.function.name=findByEmail, mongoose.method.name=findByEmail, mongoose.method.type=static, mongoose.method.model=User, db.collection.name=users, mongoose.method.parameter_count=1, mongoose.method.parameters=["A***@***.com"]
+
+✓ mongoose.User.describe                 27µs [autotel-mongoose]
+     db.system.name=mongodb, code.function.name=describe, mongoose.method.name=describe, mongoose.method.type=instance, mongoose.method.model=User, db.collection.name=users, mongoose.method.parameter_count=0
+
+✓ mongoose.User.countByDomain             2ms [autotel-mongoose]
+     db.system.name=mongodb, code.function.name=countByDomain, mongoose.method.name=countByDomain, mongoose.method.type=static, mongoose.method.model=User, db.collection.name=users, mongoose.method.parameter_count=1, mongoose.method.parameters=["hotmail.com"]
+
+✓ mongoose.User.byEmailDomain            82µs [autotel-mongoose]
+     db.system.name=mongodb, code.function.name=byEmailDomain, mongoose.method.name=byEmailDomain, mongoose.method.type=query, mongoose.method.model=User, db.collection.name=users, mongoose.method.parameter_count=1, mongoose.method.parameters=["hotmail.com"]
+```
+
+As JSON:
+
+```json
+{
+  "name": "mongoose.User.findByEmail",
+  "kind": "INTERNAL",
+  "instrumentationScope": { "name": "autotel-mongoose" },
+  "attributes": {
+    "db.system.name": "mongodb",
+    "code.function.name": "findByEmail",
+    "mongoose.method.name": "findByEmail",
+    "mongoose.method.type": "static",
+    "mongoose.method.model": "User",
+    "db.collection.name": "users",
+    "mongoose.method.parameter_count": 1,
+    "mongoose.method.parameters": "[\"A***@***.com\"]"
+  }
+}
+```
+
+Span attributes: `mongoose.method.name`, `mongoose.method.type`
+(`static` | `instance` | `query`), `mongoose.method.model`, `code.function.name`,
+and — when parameter capture is on — `mongoose.method.parameters` (+
+`mongoose.method.parameter_count`).
+
+> **Behavior note (default on):** With no `customMethods` option, `instrumentMongoose(mongoose)`
+> wraps **all** custom functions and captures their arguments by default
+> (maximum observability). Arguments pass through the same redactor as
+> `db.query.text`, but custom-function args are often business payloads rather
+> than DB filters — redaction won't catch arbitrary fields. Use the options
+> below to scope this down for privacy/compliance.
+
+### Opting out / scoping (privacy & compliance)
+
+```typescript
+// Disable entirely
+instrumentMongoose(mongoose, { customMethods: false });
+
+// Per-category control. Anything not explicitly disabled stays on.
+instrumentMongoose(mongoose, {
+  customMethods: {
+    statics: { exclude: ['chargeCard'] }, // opt-out specific statics
+    methods: ['describe'], //               opt-in: only these instance methods
+    query: false, //                        no query helpers
+    captureParameters: false, //            trace calls, don't serialize args
+  },
+});
+
+// Keep tracing, but never serialize arguments anywhere
+instrumentMongoose(mongoose, { customMethods: { captureParameters: false } });
+
+// Custom parameter serializer / longer cap / dedicated redactor
+instrumentMongoose(mongoose, {
+  customMethods: {
+    captureParameters: {
+      maxLength: 4096,
+      redactor: 'default',
+      serializer: (args, { methodName }) =>
+        methodName === 'chargeCard' ? undefined : JSON.stringify(args),
+    },
+  },
+});
+```
+
+A selector accepts `true` (all), `false` (none), `string[]` (opt-in to those
+names), or `{ include?, exclude? }`. Config is resolved **per Mongoose
+instance** at call time, so a schema object reused across multiple
+instances/connections honors each instance's own configuration.
+
 ## Configuration
 
 ```typescript
@@ -91,6 +202,7 @@ const config: InstrumentMongooseConfig = {
   instrumentHooks: false,
   dbStatementSerializer: false,
   statementRedactor: 'default',
+  customMethods: true, // wrap all custom statics/methods/query helpers (default)
 };
 ```
 
@@ -137,13 +249,15 @@ instrumentMongoose(mongoose, {
 - `instrumentMongoose(mongoose, config?)`
 - `InstrumentMongooseConfig`
 - `SerializerPayload`
+- `CustomMethodsConfig`, `CustomMethodType`, `MethodSelector`, `ParameterCaptureConfig`
 
 ## Notes
 
 - Query and aggregate operations are traced automatically
 - Instance methods like `save()` and `deleteOne()` are traced
 - Static methods like `create()`, `insertMany()`, `aggregate()`, and `bulkWrite()` are traced
-- Hook spans use `SpanKind.INTERNAL`
+- User-defined statics, instance methods, and query helpers are traced automatically (see above)
+- Hook and custom-function spans use `SpanKind.INTERNAL`
 
 ## License
 

package/dist/index.cjs

@@ -13,6 +13,12 @@ var ATTR_DB_COLLECTION_NAME = "db.collection.name";
 var ATTR_DB_NAMESPACE = "db.namespace";
 var ATTR_SERVER_ADDRESS = "server.address";
 var ATTR_SERVER_PORT = "server.port";
+var ATTR_CODE_FUNCTION_NAME = "code.function.name";
+var ATTR_MONGOOSE_METHOD_NAME = "mongoose.method.name";
+var ATTR_MONGOOSE_METHOD_TYPE = "mongoose.method.type";
+var ATTR_MONGOOSE_METHOD_MODEL = "mongoose.method.model";
+var ATTR_MONGOOSE_METHOD_PARAMETERS = "mongoose.method.parameters";
+var ATTR_MONGOOSE_METHOD_PARAMETER_COUNT = "mongoose.method.parameter_count";
 var DB_SYSTEM_NAME_VALUE_MONGODB = "mongodb";
 
 // src/types.ts
@@ -39,10 +45,99 @@ function createStatementCapture(config) {
     return redact ? redact(raw) : raw;
   };
 }
+var DEFAULT_PARAMETER_MAX_LENGTH = 2048;
+function defaultParameterSerializer(args) {
+  if (args.length === 0) {
+    return void 0;
+  }
+  const seen = /* @__PURE__ */ new WeakSet();
+  const replacer = (_key, value) => {
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
+    if (typeof value === "function") {
+      return "[Function]";
+    }
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) {
+        return "[Circular]";
+      }
+      seen.add(value);
+    }
+    return value;
+  };
+  const normalized = args.map((arg) => {
+    if (arg !== null && typeof arg === "object" && typeof arg.toObject === "function") {
+      try {
+        return arg.toObject();
+      } catch {
+        return arg;
+      }
+    }
+    return arg;
+  });
+  try {
+    const json = JSON.stringify(normalized, replacer);
+    return json === void 0 ? void 0 : json;
+  } catch {
+    return void 0;
+  }
+}
+function createParameterCapture(config) {
+  const { parameterConfig } = config;
+  const maxLength = parameterConfig?.maxLength ?? DEFAULT_PARAMETER_MAX_LENGTH;
+  const serialize = parameterConfig?.serializer ?? defaultParameterSerializer;
+  const redactorSetting = parameterConfig?.redactor === void 0 ? config.statementRedactor : parameterConfig.redactor;
+  let redact;
+  if (redactorSetting !== false && redactorSetting !== void 0) {
+    redact = autotel.createStringRedactor(redactorSetting);
+  }
+  return (args, context) => {
+    const raw = serialize(args, context);
+    if (raw === void 0) {
+      return void 0;
+    }
+    const redacted = redact ? redact(raw) : raw;
+    return redacted.length > maxLength ? `${redacted.slice(0, maxLength)}\u2026[truncated]` : redacted;
+  };
+}
 
 // src/instrumentation.ts
 var INSTRUMENTED_FLAG = "__autotelMongooseInstrumented";
 var WRAPPED_HOOK_FLAG = "__autotelWrappedHook";
+var WRAPPED_METHOD_FLAG = "__autotelWrappedMethod";
+var MODEL_PATCHED_FLAG = "__autotelModelPatched";
+var INSTANCE_REGISTRY = /* @__PURE__ */ new WeakMap();
+function resolveMongooseInstance(self, methodType) {
+  try {
+    switch (methodType) {
+      case "static": {
+        return self?.base ?? self?.db?.base;
+      }
+      case "instance": {
+        return self?.constructor?.base ?? self?.db?.base;
+      }
+      case "query": {
+        return self?.model?.base;
+      }
+    }
+  } catch {
+  }
+  return void 0;
+}
+function selectorFor(cm, methodType) {
+  switch (methodType) {
+    case "static": {
+      return cm.statics;
+    }
+    case "instance": {
+      return cm.methods;
+    }
+    case "query": {
+      return cm.query;
+    }
+  }
+}
 var _STORED_PARENT_SPAN = /* @__PURE__ */ Symbol("stored-parent-span");
 function createSpan(tracer, operation, modelName, collectionName, config) {
   const spanName = collectionName ? `${operation} ${collectionName}` : modelName ? `${operation} ${modelName}` : `mongoose.${operation}`;
@@ -499,6 +594,244 @@ function wrapHookHandler(handler, hookName, hookType, tracer, config) {
   wrappedHook[WRAPPED_HOOK_FLAG] = true;
   return wrappedHook;
 }
+function resolveCustomMethods(config) {
+  const setting = config?.customMethods;
+  if (setting === false) {
+    return {
+      enabled: false,
+      statics: false,
+      methods: false,
+      query: false,
+      captureParameters: false
+    };
+  }
+  const obj = setting === void 0 || setting === true ? {} : setting;
+  const cp = obj.captureParameters;
+  let captureParameters = false;
+  if (cp !== false) {
+    captureParameters = createParameterCapture({
+      parameterConfig: cp === void 0 || cp === true ? void 0 : cp,
+      // Parameters inherit the same PII redaction as db.query.text by default.
+      statementRedactor: config?.statementRedactor ?? "default"
+    });
+  }
+  return {
+    enabled: true,
+    statics: obj.statics ?? true,
+    methods: obj.methods ?? true,
+    query: obj.query ?? true,
+    captureParameters
+  };
+}
+function selectorAllows(selector, name) {
+  if (selector === false) {
+    return false;
+  }
+  if (selector === true) {
+    return true;
+  }
+  if (Array.isArray(selector)) {
+    return selector.includes(name);
+  }
+  if (selector.include && !selector.include.includes(name)) {
+    return false;
+  }
+  if (selector.exclude && selector.exclude.includes(name)) {
+    return false;
+  }
+  return true;
+}
+function resolveModelContext(self, methodType) {
+  try {
+    switch (methodType) {
+      case "static": {
+        return {
+          modelName: self?.modelName,
+          collectionName: self?.collection?.collectionName || self?.modelName
+        };
+      }
+      case "instance": {
+        const ctor = self?.constructor;
+        return {
+          modelName: ctor?.modelName,
+          collectionName: ctor?.collection?.collectionName || ctor?.modelName
+        };
+      }
+      case "query": {
+        const model = self?.model;
+        return {
+          modelName: model?.modelName,
+          collectionName: model?.collection?.collectionName || model?.modelName
+        };
+      }
+    }
+  } catch {
+  }
+  return {};
+}
+function wrapCustomFunction(original, methodName, methodType) {
+  if (original[WRAPPED_METHOD_FLAG]) {
+    return original;
+  }
+  const wrapped = function instrumentedCustomFn(...args) {
+    const instance = resolveMongooseInstance(this, methodType);
+    const entry = instance ? INSTANCE_REGISTRY.get(instance) : void 0;
+    if (!entry || !entry.config.customMethods.enabled || !selectorAllows(
+      selectorFor(entry.config.customMethods, methodType),
+      methodName
+    )) {
+      return original.apply(this, args);
+    }
+    const { tracer, config } = entry;
+    const captureParameters = config.customMethods.captureParameters;
+    const { modelName, collectionName } = resolveModelContext(this, methodType);
+    const spanName = modelName ? `mongoose.${modelName}.${methodName}` : `mongoose.${methodType}.${methodName}`;
+    const span = tracer.startSpan(spanName, { kind: autotel.SpanKind.INTERNAL });
+    span.setAttribute(ATTR_DB_SYSTEM_NAME, DB_SYSTEM_NAME_VALUE_MONGODB);
+    span.setAttribute(ATTR_CODE_FUNCTION_NAME, methodName);
+    span.setAttribute(ATTR_MONGOOSE_METHOD_NAME, methodName);
+    span.setAttribute(ATTR_MONGOOSE_METHOD_TYPE, methodType);
+    if (modelName) {
+      span.setAttribute(ATTR_MONGOOSE_METHOD_MODEL, modelName);
+    }
+    if (collectionName && config.captureCollectionName) {
+      span.setAttribute(ATTR_DB_COLLECTION_NAME, collectionName);
+    }
+    if (config.dbName) {
+      span.setAttribute(ATTR_DB_NAMESPACE, config.dbName);
+    }
+    if (captureParameters) {
+      span.setAttribute(ATTR_MONGOOSE_METHOD_PARAMETER_COUNT, args.length);
+      try {
+        const params = captureParameters(args, { methodName, methodType });
+        if (params !== void 0) {
+          span.setAttribute(ATTR_MONGOOSE_METHOD_PARAMETERS, params);
+        }
+      } catch {
+      }
+    }
+    return traceHelpers.runWithSpan(span, () => {
+      try {
+        const result = original.apply(this, args);
+        if (methodType === "query") {
+          traceHelpers.finalizeSpan(span);
+          return result;
+        }
+        if (result && typeof result.exec === "function") {
+          const originalExec = result.exec.bind(result);
+          result.exec = function wrappedExec() {
+            try {
+              return Promise.resolve(originalExec()).then((value) => {
+                traceHelpers.finalizeSpan(span);
+                return value;
+              }).catch((error) => {
+                traceHelpers.finalizeSpan(
+                  span,
+                  error instanceof Error ? error : new Error(String(error))
+                );
+                throw error;
+              });
+            } catch (error) {
+              traceHelpers.finalizeSpan(
+                span,
+                error instanceof Error ? error : new Error(String(error))
+              );
+              throw error;
+            }
+          };
+          return result;
+        }
+        if (result && typeof result.then === "function") {
+          return Promise.resolve(result).then((value) => {
+            traceHelpers.finalizeSpan(span);
+            return value;
+          }).catch((error) => {
+            traceHelpers.finalizeSpan(
+              span,
+              error instanceof Error ? error : new Error(String(error))
+            );
+            throw error;
+          });
+        }
+        traceHelpers.finalizeSpan(span);
+        return result;
+      } catch (error) {
+        traceHelpers.finalizeSpan(
+          span,
+          error instanceof Error ? error : new Error(String(error))
+        );
+        throw error;
+      }
+    });
+  };
+  try {
+    Object.defineProperty(wrapped, "name", {
+      value: original.name || methodName,
+      configurable: true
+    });
+  } catch {
+  }
+  wrapped[WRAPPED_METHOD_FLAG] = true;
+  return wrapped;
+}
+var MONGOOSE_INTERNAL_FUNCTION_NAMES = /* @__PURE__ */ new Set([
+  "initializeTimestamps"
+]);
+function isMongooseInternalFunctionName(name) {
+  return name.startsWith("$") || MONGOOSE_INTERNAL_FUNCTION_NAMES.has(name);
+}
+function instrumentSchemaCustomFunctions(schema) {
+  if (!schema) {
+    return;
+  }
+  const wrapCollection = (collection, methodType) => {
+    if (!collection) {
+      return;
+    }
+    for (const name of Object.keys(collection)) {
+      if (isMongooseInternalFunctionName(name)) {
+        continue;
+      }
+      const fn = collection[name];
+      if (typeof fn !== "function" || fn[WRAPPED_METHOD_FLAG]) {
+        continue;
+      }
+      collection[name] = wrapCustomFunction(fn, name, methodType);
+    }
+  };
+  wrapCollection(schema.statics, "static");
+  wrapCollection(schema.methods, "instance");
+  wrapCollection(schema.query, "query");
+}
+function patchModelFactory(m, config) {
+  if (!config.customMethods.enabled) {
+    return;
+  }
+  const patchHost = (host) => {
+    if (!host || typeof host.model !== "function" || host[MODEL_PATCHED_FLAG]) {
+      return;
+    }
+    const originalModel = host.model;
+    host.model = function patchedModel(nameOrSchema, schema, ...rest) {
+      if (schema && typeof schema === "object") {
+        try {
+          instrumentSchemaCustomFunctions(schema);
+        } catch {
+        }
+      }
+      return Reflect.apply(originalModel, this, [
+        nameOrSchema,
+        schema,
+        ...rest
+      ]);
+    };
+    host[MODEL_PATCHED_FLAG] = true;
+  };
+  patchHost(m);
+  if (m.Connection?.prototype) {
+    patchHost(m.Connection.prototype);
+  }
+}
 function instrumentMongoose(mongoose, config) {
   if (!mongoose?.Model) {
     return mongoose;
@@ -515,8 +848,14 @@ function instrumentMongoose(mongoose, config) {
     peerPort: config?.peerPort || 27017,
     tracerName: config?.tracerName || DEFAULT_TRACER_NAME,
     captureCollectionName: config?.captureCollectionName ?? true,
-    instrumentHooks: config?.instrumentHooks ?? false};
+    instrumentHooks: config?.instrumentHooks ?? false,
+    dbStatementSerializer: resolvedSerializer === false ? false : resolvedSerializer ?? defaultSerializer,
+    statementRedactor: resolvedRedactor,
+    customMethods: resolveCustomMethods(config)
+  };
   const tracer = autotel.otelTrace.getTracer(finalConfig.tracerName);
+  INSTANCE_REGISTRY.set(mongoose, { tracer, config: finalConfig });
+  patchModelFactory(m, finalConfig);
   const captureStatement = createStatementCapture({
     dbStatementSerializer: resolvedSerializer,
     statementRedactor: resolvedRedactor