@twin.org/tracing-facades 0.9.3-next.3

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 IOTA Stiftung.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,21 @@
+# TWIN Tracing Facades
+
+Applies tracing to factory produced components using a facade, without modifying them.
+
+## Installation
+
+```shell
+npm install @twin.org/tracing-facades
+```
+
+## Examples
+
+Usage of the APIs is shown in the examples [docs/examples.md](docs/examples.md)
+
+## Reference
+
+Detailed reference documentation for the API can be found in [docs/reference/index.md](docs/reference/index.md)
+
+## Changelog
+
+The changes between each version can be found in [docs/changelog.md](docs/changelog.md)

package/dist/es/index.js

@@ -0,0 +1,7 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export * from "./models/ITracingFacadeConfig.js";
+export * from "./models/ITracingFacadeConstructorOptions.js";
+export * from "./models/tracingFacadeAttributes.js";
+export * from "./tracingFacade.js";
+//# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,kCAAkC,CAAC;AACjD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,qCAAqC,CAAC;AACpD,cAAc,oBAAoB,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./models/ITracingFacadeConfig.js\";\nexport * from \"./models/ITracingFacadeConstructorOptions.js\";\nexport * from \"./models/tracingFacadeAttributes.js\";\nexport * from \"./tracingFacade.js\";\n"]}

package/dist/es/models/ITracingFacadeConfig.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=ITracingFacadeConfig.js.map

package/dist/es/models/ITracingFacadeConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITracingFacadeConfig.js","sourceRoot":"","sources":["../../../src/models/ITracingFacadeConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Configuration for the tracing facade.\n *\n * The method and parameter patterns are dot separated and matched from the right, so `password`\n * and `*.*.password` both match a parameter of that name on any method of any class, while\n * `NotarizationService.create.controllerIdentity` matches only that one. A `*` matches any single\n * segment.\n */\nexport interface ITracingFacadeConfig {\n\t/**\n\t * Patterns for parameters whose values are never recorded, whatever their type, matched\n\t * against `class.method.parameter`. Supplying this replaces TracingFacade.DEFAULT_EXCLUDE_PARAMS.\n\t */\n\texcludeParams?: string[];\n\n\t/**\n\t * Patterns for methods which are not intercepted at all, matched against `class.method`.\n\t * Supplying this replaces TracingFacade.DEFAULT_EXCLUDE_METHODS.\n\t */\n\texcludeMethods?: string[];\n\n\t/**\n\t * Patterns for parameters to record even when the value is not primitive, matched against\n\t * `class.method.parameter`. A further segment selects a single property, so\n\t * `NotarizationService.create.notarization.mode` records only the mode. Any other non\n\t * primitive parameter is not recorded.\n\t */\n\tincludeObjects?: string[];\n\n\t/**\n\t * The maximum length of a recorded string, longer values are truncated.\n\t * @default 256\n\t */\n\tmaxStringLength?: number;\n\n\t/**\n\t * The maximum number of entries recorded for an array.\n\t * @default 10\n\t */\n\tmaxArrayLength?: number;\n}\n"]}

package/dist/es/models/ITracingFacadeConstructorOptions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ITracingFacadeConstructorOptions.js.map

package/dist/es/models/ITracingFacadeConstructorOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITracingFacadeConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/ITracingFacadeConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { ITracingFacadeConfig } from \"./ITracingFacadeConfig.js\";\n\n/**\n * Options for the tracing facade constructor.\n */\nexport interface ITracingFacadeConstructorOptions {\n\t/**\n\t * The component type for the optional tracing component used for spans. When it does not\n\t * resolve the facade passes every call straight through.\n\t */\n\ttracingComponentType?: string;\n\n\t/**\n\t * The component type for the optional logging component, used to report a tracing failure.\n\t */\n\tloggingComponentType?: string;\n\n\t/**\n\t * The configuration for the facade.\n\t */\n\tconfig?: ITracingFacadeConfig;\n}\n"]}

package/dist/es/models/tracingFacadeAttributes.js

@@ -0,0 +1,21 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The span attribute keys recorded by the tracing facade.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const TracingFacadeAttributes = {
+    /**
+     * The name of the method the span covers.
+     */
+    Method: "method.name",
+    /**
+     * The prefix for the recorded parameter values.
+     */
+    ParamPrefix: "param.",
+    /**
+     * The returned value.
+     */
+    Result: "method.result"
+};
+//# sourceMappingURL=tracingFacadeAttributes.js.map

package/dist/es/models/tracingFacadeAttributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracingFacadeAttributes.js","sourceRoot":"","sources":["../../../src/models/tracingFacadeAttributes.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC;;OAEG;IACH,MAAM,EAAE,aAAa;IAErB;;OAEG;IACH,WAAW,EAAE,QAAQ;IAErB;;OAEG;IACH,MAAM,EAAE,eAAe;CACd,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * The span attribute keys recorded by the tracing facade.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const TracingFacadeAttributes = {\n\t/**\n\t * The name of the method the span covers.\n\t */\n\tMethod: \"method.name\",\n\n\t/**\n\t * The prefix for the recorded parameter values.\n\t */\n\tParamPrefix: \"param.\",\n\n\t/**\n\t * The returned value.\n\t */\n\tResult: \"method.result\"\n} as const;\n\n/**\n * Union type of all tracing facade attribute string values.\n */\nexport type TracingFacadeAttributes =\n\t(typeof TracingFacadeAttributes)[keyof typeof TracingFacadeAttributes];\n"]}

package/dist/es/tracingFacade.js

@@ -0,0 +1,371 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { ComponentFactory, Is } from "@twin.org/core";
+import { TracingHelper } from "@twin.org/tracing-models";
+import { TracingFacadeAttributes } from "./models/tracingFacadeAttributes.js";
+/**
+ * Facade which records a span for each external call to an async method on the component it wraps,
+ * so a component can be traced without being modified.
+ *
+ * Only methods declared async are traced. A span cannot be opened synchronously, so wrapping a
+ * synchronous method would make it return a promise and break the contract of the wrapped
+ * component.
+ */
+export class TracingFacade {
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "TracingFacade";
+    /**
+     * The methods that are excluded from tracing by default.
+     */
+    static DEFAULT_EXCLUDE_METHODS = [
+        "start",
+        "stop",
+        "bootstrap",
+        "teardown"
+    ];
+    /**
+     * The parameters that are excluded from recording by default.
+     */
+    static DEFAULT_EXCLUDE_PARAMS = [
+        "password",
+        "token",
+        "apiKey",
+        "mnemonic"
+    ];
+    /**
+     * The default maximum length of a recorded string.
+     */
+    static DEFAULT_MAX_STRING_LENGTH = 256;
+    /**
+     * The default maximum number of entries recorded for an array.
+     */
+    static DEFAULT_MAX_ARRAY_LENGTH = 10;
+    /**
+     * The name a returned value is matched under, so it can be excluded or have a property
+     * selected with the same patterns as a parameter.
+     */
+    static RESULT_NAME = "resolved";
+    /**
+     * A camel case parameter name, used to check the names read from the source are trustworthy.
+     * @internal
+     */
+    static _IDENTIFIER = /^[a-z][A-Za-z0-9]*$/;
+    /**
+     * The result of Object.prototype.toString for a method declared async. Used in preference to
+     * the constructor name, which throws for a function with no prototype.
+     * @internal
+     */
+    static _ASYNC_FUNCTION_TAG = "[object AsyncFunction]";
+    /**
+     * The component recording the spans, when absent every call passes straight through.
+     * @internal
+     */
+    _tracingComponent;
+    /**
+     * The component for logging a tracing failure.
+     * @internal
+     */
+    _loggingComponent;
+    /**
+     * Patterns for parameters whose values are never recorded.
+     * @internal
+     */
+    _excludeParams;
+    /**
+     * Patterns for methods which are not intercepted.
+     * @internal
+     */
+    _excludeMethods;
+    /**
+     * Patterns for parameters to record even when the value is not primitive.
+     * @internal
+     */
+    _includeObjects;
+    /**
+     * The maximum length of a recorded string.
+     * @internal
+     */
+    _maxStringLength;
+    /**
+     * The maximum number of entries recorded for an array.
+     * @internal
+     */
+    _maxArrayLength;
+    /**
+     * The wrapper for each method, held against the target as well as the method.
+     * @internal
+     */
+    _wrappers;
+    /**
+     * The parameter names of each method, parsed once on first use.
+     * @internal
+     */
+    _paramNames;
+    /**
+     * Create a new instance of TracingFacade.
+     * @param options The options for the facade.
+     */
+    constructor(options) {
+        this._tracingComponent = ComponentFactory.getIfExists(options?.tracingComponentType);
+        this._loggingComponent = ComponentFactory.getIfExists(options?.loggingComponentType);
+        this._excludeParams = (options?.config?.excludeParams ?? TracingFacade.DEFAULT_EXCLUDE_PARAMS).map(pattern => pattern.split("."));
+        this._excludeMethods = (options?.config?.excludeMethods ?? TracingFacade.DEFAULT_EXCLUDE_METHODS).map(pattern => pattern.split("."));
+        this._includeObjects = (options?.config?.includeObjects ?? []).map(pattern => {
+            const segments = pattern.split(".");
+            return {
+                path: segments,
+                root: segments.slice(0, -1),
+                last: segments[segments.length - 1]
+            };
+        });
+        this._maxStringLength =
+            options?.config?.maxStringLength ?? TracingFacade.DEFAULT_MAX_STRING_LENGTH;
+        this._maxArrayLength =
+            options?.config?.maxArrayLength ?? TracingFacade.DEFAULT_MAX_ARRAY_LENGTH;
+        this._wrappers = new WeakMap();
+        this._paramNames = new WeakMap();
+    }
+    /**
+     * Wrap the target so its method calls are recorded as spans.
+     * @param target The component to wrap.
+     * @returns The wrapped component, or the target itself when there is no tracing component.
+     */
+    wrap(target) {
+        if (Is.empty(this._tracingComponent)) {
+            return target;
+        }
+        return new Proxy(target, {
+            get: (t, prop, receiver) => this.interceptGet(t, prop, receiver)
+        });
+    }
+    /**
+     * Intercept a property read, returning a replacement function for a method which should be
+     * traced, and the value itself for anything else.
+     * @param target The component being wrapped.
+     * @param prop The property being read.
+     * @param receiver The proxy the read was made through.
+     * @returns The value for the property.
+     * @internal
+     */
+    interceptGet(target, prop, receiver) {
+        const value = Reflect.get(target, prop, receiver);
+        if (!Is.function(value) || !Is.string(prop)) {
+            return value;
+        }
+        // Wrapping a synchronous method would make it return a promise. The declaration is tested
+        // rather than the return value, which would open the span too late to nest inner calls.
+        if (Object.prototype.toString.call(value) !== TracingFacade._ASYNC_FUNCTION_TAG) {
+            return value;
+        }
+        const className = this.className(target);
+        if (this.matchesAny(this._excludeMethods, [className, prop])) {
+            return value;
+        }
+        return this.tracedMethod(target, className, prop, value);
+    }
+    /**
+     * Get the wrapper for a method, building it on first use.
+     * @param target The component being wrapped.
+     * @param className The name of the component class.
+     * @param name The name of the method.
+     * @param method The method to wrap.
+     * @returns The wrapper, which is the same function for every read of that method.
+     * @internal
+     */
+    tracedMethod(target, className, name, method) {
+        let wrappers = this._wrappers.get(target);
+        if (Is.undefined(wrappers)) {
+            wrappers = new WeakMap();
+            this._wrappers.set(target, wrappers);
+        }
+        let wrapper = wrappers.get(method);
+        if (Is.undefined(wrapper)) {
+            wrapper = async (...args) => TracingHelper.withSpan(this._tracingComponent, Is.stringValue(className) ? `method:${className}.${name}` : `method:${name}`, { attributes: this.callAttributes(className, name, method, args) }, async (span) => {
+                const resolved = await method.apply(target, args);
+                if (!Is.empty(span)) {
+                    const recorded = this.attributeValue([className, name, TracingFacade.RESULT_NAME], resolved);
+                    if (!Is.undefined(recorded)) {
+                        span.attributes = {
+                            ...span.attributes,
+                            [TracingFacadeAttributes.Result]: recorded
+                        };
+                    }
+                }
+                return resolved;
+            }, this._loggingComponent);
+            wrappers.set(method, wrapper);
+        }
+        return wrapper;
+    }
+    /**
+     * Build the attributes describing a call.
+     * @param className The name of the component class.
+     * @param name The name of the method.
+     * @param method The method being called.
+     * @param args The arguments the method was called with.
+     * @returns The attributes.
+     * @internal
+     */
+    callAttributes(className, name, method, args) {
+        const attributes = {
+            [TracingFacadeAttributes.Method]: Is.stringValue(className) ? `${className}.${name}` : name
+        };
+        const paramNames = this.paramNames(method);
+        for (let i = 0; i < args.length; i++) {
+            const paramName = paramNames[i];
+            if (Is.stringValue(paramName)) {
+                const recorded = this.attributeValue([className, name, paramName], args[i]);
+                if (!Is.undefined(recorded)) {
+                    attributes[`${TracingFacadeAttributes.ParamPrefix}${paramName}`] = recorded;
+                }
+            }
+        }
+        return attributes;
+    }
+    /**
+     * Decide what is recorded for a value, applying the exclusions, the object selection and the
+     * length limits.
+     * @param path The class, method and parameter name the value belongs to.
+     * @param value The value to record.
+     * @returns The value to record, or undefined when nothing is recorded.
+     * @internal
+     */
+    attributeValue(path, value) {
+        if (this.matchesAny(this._excludeParams, path)) {
+            return undefined;
+        }
+        const primitive = this.primitiveValue(value);
+        if (!Is.undefined(primitive)) {
+            return primitive;
+        }
+        const included = this.included(path);
+        if (!included.record) {
+            return undefined;
+        }
+        if (Is.arrayValue(included.properties)) {
+            if (!Is.object(value)) {
+                return undefined;
+            }
+            const selected = {};
+            for (const property of included.properties) {
+                selected[property] = value[property];
+            }
+            return selected;
+        }
+        return Is.array(value) ? value.slice(0, this._maxArrayLength) : value;
+    }
+    /**
+     * Convert a value which can be recorded as a span attribute directly.
+     * @param value The value to convert.
+     * @returns The value to record, or undefined when it is not a primitive.
+     * @internal
+     */
+    primitiveValue(value) {
+        if (Is.string(value)) {
+            return value.length > this._maxStringLength ? value.slice(0, this._maxStringLength) : value;
+        }
+        // A bigint cannot be serialised by JSON.stringify, so it is converted here.
+        if (Is.bigint(value)) {
+            return String(value);
+        }
+        if (Is.number(value) || Is.boolean(value) || Is.null(value)) {
+            return value;
+        }
+        return undefined;
+    }
+    /**
+     * Decide whether a non primitive value is recorded, and which of its properties are.
+     * @param path The class, method and parameter name the value belongs to.
+     * @returns Whether to record the value, and the properties to record when the patterns select
+     * them rather than the whole value.
+     * @internal
+     */
+    included(path) {
+        const properties = [];
+        for (const pattern of this._includeObjects) {
+            // The parameter itself is named, so the whole value is recorded.
+            if (this.matches(pattern.path, path)) {
+                return { record: true };
+            }
+            if (pattern.root.length > 0 && this.matches(pattern.root, path)) {
+                properties.push(pattern.last);
+            }
+        }
+        return properties.length > 0 ? { record: true, properties } : { record: false };
+    }
+    /**
+     * Does any of the patterns match the path.
+     * @param patterns The patterns to test.
+     * @param path The path to test them against.
+     * @returns True when one of the patterns matches.
+     * @internal
+     */
+    matchesAny(patterns, path) {
+        return patterns.some(pattern => this.matches(pattern, path));
+    }
+    /**
+     * Does a dot separated pattern match a path. The pattern is matched from the right, so a
+     * pattern shorter than the path leaves the leading segments unconstrained, and a `*` matches
+     * any single segment.
+     * @param segments The segments of the pattern to test.
+     * @param path The path to test it against.
+     * @returns True when the pattern matches.
+     * @internal
+     */
+    matches(segments, path) {
+        if (segments.length > path.length) {
+            return false;
+        }
+        const offset = path.length - segments.length;
+        return segments.every((segment, index) => segment === "*" || segment === path[offset + index]);
+    }
+    /**
+     * Get the name of the component class, which every IComponent implementation provides.
+     * @param target The component to get the name of.
+     * @returns The class name, or an empty string when the component does not provide one.
+     * @internal
+     */
+    className(target) {
+        const method = target.className;
+        if (Is.function(method)) {
+            const name = method.call(target);
+            if (Is.stringValue(name)) {
+                return name;
+            }
+        }
+        return "";
+    }
+    /**
+     * Get the parameter names of a method, read from its source and held for reuse. An empty list
+     * is returned when the names cannot be read reliably, so no parameter values are recorded
+     * rather than being recorded against a name which may be wrong.
+     * @param method The method to read the parameter names of.
+     * @returns The parameter names in order, or an empty list when they cannot be trusted.
+     * @internal
+     */
+    paramNames(method) {
+        let names = this._paramNames.get(method);
+        if (Is.undefined(names)) {
+            const source = method.toString();
+            const open = source.indexOf("(");
+            const close = source.indexOf(")", open);
+            names =
+                open === -1 || close === -1
+                    ? []
+                    : source
+                        .slice(open + 1, close)
+                        .split(",")
+                        .map(param => param.trim())
+                        .filter(param => param.length > 0);
+            // Anything which is not a plain identifier means the whole list is suspect, so nothing is trusted.
+            if (!names.every(name => TracingFacade._IDENTIFIER.test(name))) {
+                names = [];
+            }
+            this._paramNames.set(method, names);
+        }
+        return names;
+    }
+}
+//# sourceMappingURL=tracingFacade.js.map

package/dist/es/tracingFacade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracingFacade.js","sourceRoot":"","sources":["../../src/tracingFacade.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,gBAAgB,EAAE,EAAE,EAAgB,MAAM,gBAAgB,CAAC;AAGpE,OAAO,EAAE,aAAa,EAA0B,MAAM,0BAA0B,CAAC;AAEjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,OAAO,aAAa;IACzB;;OAEG;IACI,MAAM,CAAU,UAAU,mBAAmC;IAEpE;;OAEG;IACI,MAAM,CAAU,uBAAuB,GAAa;QAC1D,OAAO;QACP,MAAM;QACN,WAAW;QACX,UAAU;KACV,CAAC;IAEF;;OAEG;IACI,MAAM,CAAU,sBAAsB,GAAa;QACzD,UAAU;QACV,OAAO;QACP,QAAQ;QACR,UAAU;KACV,CAAC;IAEF;;OAEG;IACI,MAAM,CAAU,yBAAyB,GAAW,GAAG,CAAC;IAE/D;;OAEG;IACI,MAAM,CAAU,wBAAwB,GAAW,EAAE,CAAC;IAE7D;;;OAGG;IACI,MAAM,CAAU,WAAW,GAAW,UAAU,CAAC;IAExD;;;OAGG;IACK,MAAM,CAAU,WAAW,GAAW,qBAAqB,CAAC;IAEpE;;;;OAIG;IACK,MAAM,CAAU,mBAAmB,GAAW,wBAAwB,CAAC;IAE/E;;;OAGG;IACc,iBAAiB,CAAqB;IAEvD;;;OAGG;IACc,iBAAiB,CAAqB;IAEvD;;;OAGG;IACc,cAAc,CAAa;IAE5C;;;OAGG;IACc,eAAe,CAAa;IAE7C;;;OAGG;IACc,eAAe,CAAqD;IAErF;;;OAGG;IACc,gBAAgB,CAAS;IAE1C;;;OAGG;IACc,eAAe,CAAS;IAEzC;;;OAGG;IACc,SAAS,CAGxB;IAEF;;;OAGG;IACc,WAAW,CAA4B;IAExD;;;OAGG;IACH,YAAY,OAA0C;QACrD,IAAI,CAAC,iBAAiB,GAAG,gBAAgB,CAAC,WAAW,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QACrF,IAAI,CAAC,iBAAiB,GAAG,gBAAgB,CAAC,WAAW,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QACrF,IAAI,CAAC,cAAc,GAAG,CACrB,OAAO,EAAE,MAAM,EAAE,aAAa,IAAI,aAAa,CAAC,sBAAsB,CACtE,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACrC,IAAI,CAAC,eAAe,GAAG,CACtB,OAAO,EAAE,MAAM,EAAE,cAAc,IAAI,aAAa,CAAC,uBAAuB,CACxE,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACrC,IAAI,CAAC,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE;YAC5E,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAEpC,OAAO;gBACN,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC3B,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;aACnC,CAAC;QACH,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,gBAAgB;YACpB,OAAO,EAAE,MAAM,EAAE,eAAe,IAAI,aAAa,CAAC,yBAAyB,CAAC;QAC7E,IAAI,CAAC,eAAe;YACnB,OAAO,EAAE,MAAM,EAAE,cAAc,IAAI,aAAa,CAAC,wBAAwB,CAAC;QAC3E,IAAI,CAAC,SAAS,GAAG,IAAI,OAAO,EAAE,CAAC;QAC/B,IAAI,CAAC,WAAW,GAAG,IAAI,OAAO,EAAE,CAAC;IAClC,CAAC;IAED;;;;OAIG;IACI,IAAI,CAAI,MAAS;QACvB,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACtC,OAAO,MAAM,CAAC;QACf,CAAC;QAED,OAAO,IAAI,KAAK,CAAC,MAAoC,EAAE;YACtD,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAW,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC;SACzE,CAAM,CAAC;IACT,CAAC;IAED;;;;;;;;OAQG;IACK,YAAY,CACnB,MAAkC,EAClC,IAAqB,EACrB,QAAiB;QAEjB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QAElD,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7C,OAAO,KAAK,CAAC;QACd,CAAC;QAED,0FAA0F;QAC1F,wFAAwF;QACxF,IAAI,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,aAAa,CAAC,mBAAmB,EAAE,CAAC;YACjF,OAAO,KAAK,CAAC;QACd,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAEzC,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;YAC9D,OAAO,KAAK,CAAC;QACd,CAAC;QAED,OAAO,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;;;OAQG;IACK,YAAY,CACnB,MAAkC,EAClC,SAAiB,EACjB,IAAY,EACZ,MAAuC;QAEvC,IAAI,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAE1C,IAAI,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC5B,QAAQ,GAAG,IAAI,OAAO,EAAE,CAAC;YACzB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACtC,CAAC;QAED,IAAI,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAEnC,IAAI,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,OAAO,GAAG,KAAK,EAAE,GAAG,IAAe,EAAoB,EAAE,CACxD,aAAa,CAAC,QAAQ,CACrB,IAAI,CAAC,iBAAiB,EACtB,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,EAC5E,EAAE,UAAU,EAAE,IAAI,CAAC,cAAc,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAClE,KAAK,EAAC,IAAI,EAAC,EAAE;gBACZ,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBAElD,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;oBACrB,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CACnC,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,CAAC,WAAW,CAAC,EAC5C,QAAQ,CACR,CAAC;oBAEF,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;wBAC7B,IAAI,CAAC,UAAU,GAAG;4BACjB,GAAG,IAAI,CAAC,UAAU;4BAClB,CAAC,uBAAuB,CAAC,MAAM,CAAC,EAAE,QAAQ;yBAC1C,CAAC;oBACH,CAAC;gBACF,CAAC;gBAED,OAAO,QAAQ,CAAC;YACjB,CAAC,EACD,IAAI,CAAC,iBAAiB,CACtB,CAAC;YAEH,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,CAAC;QAED,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;;;;;;;OAQG;IACK,cAAc,CACrB,SAAiB,EACjB,IAAY,EACZ,MAAuC,EACvC,IAAe;QAEf,MAAM,UAAU,GAA+B;YAC9C,CAAC,uBAAuB,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;SAC3F,CAAC;QAEF,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAE3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YAEhC,IAAI,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,SAAS,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;gBAE5E,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC7B,UAAU,CAAC,GAAG,uBAAuB,CAAC,WAAW,GAAG,SAAS,EAAE,CAAC,GAAG,QAAQ,CAAC;gBAC7E,CAAC;YACF,CAAC;QACF,CAAC;QAED,OAAO,UAAU,CAAC;IACnB,CAAC;IAED;;;;;;;OAOG;IACK,cAAc,CAAC,IAAc,EAAE,KAAc;QACpD,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,cAAc,EAAE,IAAI,CAAC,EAAE,CAAC;YAChD,OAAO,SAAS,CAAC;QAClB,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QAE7C,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,OAAO,SAAS,CAAC;QAClB,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAErC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACtB,OAAO,SAAS,CAAC;QAClB,CAAC;QAED,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC,EAAE,CAAC,MAAM,CAA6B,KAAK,CAAC,EAAE,CAAC;gBACnD,OAAO,SAAS,CAAC;YAClB,CAAC;YAED,MAAM,QAAQ,GAA+B,EAAE,CAAC;YAChD,KAAK,MAAM,QAAQ,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;gBAC5C,QAAQ,CAAC,QAAQ,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;YACtC,CAAC;YAED,OAAO,QAAQ,CAAC;QACjB,CAAC;QAED,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACvE,CAAC;IAED;;;;;OAKG;IACK,cAAc,CAAC,KAAc;QACpC,IAAI,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAC7F,CAAC;QAED,4EAA4E;QAC5E,IAAI,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,IAAI,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7D,OAAO,KAAK,CAAC;QACd,CAAC;QAED,OAAO,SAAS,CAAC;IAClB,CAAC;IAED;;;;;;OAMG;IACK,QAAQ,CAAC,IAAc;QAC9B,MAAM,UAAU,GAAa,EAAE,CAAC;QAEhC,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YAC5C,iEAAiE;YACjE,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;gBACtC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;YACzB,CAAC;YAED,IAAI,OAAO,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;gBACjE,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;QACF,CAAC;QAED,OAAO,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACjF,CAAC;IAED;;;;;;OAMG;IACK,UAAU,CAAC,QAAoB,EAAE,IAAc;QACtD,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;;;OAQG;IACK,OAAO,CAAC,QAAkB,EAAE,IAAc;QACjD,IAAI,QAAQ,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACnC,OAAO,KAAK,CAAC;QACd,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAE7C,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC;IAChG,CAAC;IAED;;;;;OAKG;IACK,SAAS,CAAC,MAAkC;QACnD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;QAEhC,IAAI,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAEjC,IAAI,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1B,OAAO,IAAI,CAAC;YACb,CAAC;QACF,CAAC;QAED,OAAO,EAAE,CAAC;IACX,CAAC;IAED;;;;;;;OAOG;IACK,UAAU,CAAC,MAAuC;QACzD,IAAI,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAEzC,IAAI,EAAE,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACjC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAExC,KAAK;gBACJ,IAAI,KAAK,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;oBAC1B,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,MAAM;yBACL,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,KAAK,CAAC;yBACtB,KAAK,CAAC,GAAG,CAAC;yBACV,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;yBAC1B,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAEvC,mGAAmG;YACnG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;gBAChE,KAAK,GAAG,EAAE,CAAC;YACZ,CAAC;YAED,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACrC,CAAC;QAED,OAAO,KAAK,CAAC;IACd,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { ComponentFactory, Is, type IFacade } from \"@twin.org/core\";\nimport type { ILoggingComponent } from \"@twin.org/logging-models\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { TracingHelper, type ITracingComponent } from \"@twin.org/tracing-models\";\nimport type { ITracingFacadeConstructorOptions } from \"./models/ITracingFacadeConstructorOptions.js\";\nimport { TracingFacadeAttributes } from \"./models/tracingFacadeAttributes.js\";\n\n/**\n * Facade which records a span for each external call to an async method on the component it wraps,\n * so a component can be traced without being modified.\n *\n * Only methods declared async are traced. A span cannot be opened synchronously, so wrapping a\n * synchronous method would make it return a promise and break the contract of the wrapped\n * component.\n */\nexport class TracingFacade implements IFacade {\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<TracingFacade>();\n\n\t/**\n\t * The methods that are excluded from tracing by default.\n\t */\n\tpublic static readonly DEFAULT_EXCLUDE_METHODS: string[] = [\n\t\t\"start\",\n\t\t\"stop\",\n\t\t\"bootstrap\",\n\t\t\"teardown\"\n\t];\n\n\t/**\n\t * The parameters that are excluded from recording by default.\n\t */\n\tpublic static readonly DEFAULT_EXCLUDE_PARAMS: string[] = [\n\t\t\"password\",\n\t\t\"token\",\n\t\t\"apiKey\",\n\t\t\"mnemonic\"\n\t];\n\n\t/**\n\t * The default maximum length of a recorded string.\n\t */\n\tpublic static readonly DEFAULT_MAX_STRING_LENGTH: number = 256;\n\n\t/**\n\t * The default maximum number of entries recorded for an array.\n\t */\n\tpublic static readonly DEFAULT_MAX_ARRAY_LENGTH: number = 10;\n\n\t/**\n\t * The name a returned value is matched under, so it can be excluded or have a property\n\t * selected with the same patterns as a parameter.\n\t */\n\tpublic static readonly RESULT_NAME: string = \"resolved\";\n\n\t/**\n\t * A camel case parameter name, used to check the names read from the source are trustworthy.\n\t * @internal\n\t */\n\tprivate static readonly _IDENTIFIER: RegExp = /^[a-z][A-Za-z0-9]*$/;\n\n\t/**\n\t * The result of Object.prototype.toString for a method declared async. Used in preference to\n\t * the constructor name, which throws for a function with no prototype.\n\t * @internal\n\t */\n\tprivate static readonly _ASYNC_FUNCTION_TAG: string = \"[object AsyncFunction]\";\n\n\t/**\n\t * The component recording the spans, when absent every call passes straight through.\n\t * @internal\n\t */\n\tprivate readonly _tracingComponent?: ITracingComponent;\n\n\t/**\n\t * The component for logging a tracing failure.\n\t * @internal\n\t */\n\tprivate readonly _loggingComponent?: ILoggingComponent;\n\n\t/**\n\t * Patterns for parameters whose values are never recorded.\n\t * @internal\n\t */\n\tprivate readonly _excludeParams: string[][];\n\n\t/**\n\t * Patterns for methods which are not intercepted.\n\t * @internal\n\t */\n\tprivate readonly _excludeMethods: string[][];\n\n\t/**\n\t * Patterns for parameters to record even when the value is not primitive.\n\t * @internal\n\t */\n\tprivate readonly _includeObjects: { path: string[]; root: string[]; last: string }[];\n\n\t/**\n\t * The maximum length of a recorded string.\n\t * @internal\n\t */\n\tprivate readonly _maxStringLength: number;\n\n\t/**\n\t * The maximum number of entries recorded for an array.\n\t * @internal\n\t */\n\tprivate readonly _maxArrayLength: number;\n\n\t/**\n\t * The wrapper for each method, held against the target as well as the method.\n\t * @internal\n\t */\n\tprivate readonly _wrappers: WeakMap<\n\t\tobject,\n\t\tWeakMap<object, (...args: unknown[]) => Promise<unknown>>\n\t>;\n\n\t/**\n\t * The parameter names of each method, parsed once on first use.\n\t * @internal\n\t */\n\tprivate readonly _paramNames: WeakMap<object, string[]>;\n\n\t/**\n\t * Create a new instance of TracingFacade.\n\t * @param options The options for the facade.\n\t */\n\tconstructor(options?: ITracingFacadeConstructorOptions) {\n\t\tthis._tracingComponent = ComponentFactory.getIfExists(options?.tracingComponentType);\n\t\tthis._loggingComponent = ComponentFactory.getIfExists(options?.loggingComponentType);\n\t\tthis._excludeParams = (\n\t\t\toptions?.config?.excludeParams ?? TracingFacade.DEFAULT_EXCLUDE_PARAMS\n\t\t).map(pattern => pattern.split(\".\"));\n\t\tthis._excludeMethods = (\n\t\t\toptions?.config?.excludeMethods ?? TracingFacade.DEFAULT_EXCLUDE_METHODS\n\t\t).map(pattern => pattern.split(\".\"));\n\t\tthis._includeObjects = (options?.config?.includeObjects ?? []).map(pattern => {\n\t\t\tconst segments = pattern.split(\".\");\n\n\t\t\treturn {\n\t\t\t\tpath: segments,\n\t\t\t\troot: segments.slice(0, -1),\n\t\t\t\tlast: segments[segments.length - 1]\n\t\t\t};\n\t\t});\n\t\tthis._maxStringLength =\n\t\t\toptions?.config?.maxStringLength ?? TracingFacade.DEFAULT_MAX_STRING_LENGTH;\n\t\tthis._maxArrayLength =\n\t\t\toptions?.config?.maxArrayLength ?? TracingFacade.DEFAULT_MAX_ARRAY_LENGTH;\n\t\tthis._wrappers = new WeakMap();\n\t\tthis._paramNames = new WeakMap();\n\t}\n\n\t/**\n\t * Wrap the target so its method calls are recorded as spans.\n\t * @param target The component to wrap.\n\t * @returns The wrapped component, or the target itself when there is no tracing component.\n\t */\n\tpublic wrap<T>(target: T): T {\n\t\tif (Is.empty(this._tracingComponent)) {\n\t\t\treturn target;\n\t\t}\n\n\t\treturn new Proxy(target as { [key: string]: unknown }, {\n\t\t\tget: (t, prop, receiver): unknown => this.interceptGet(t, prop, receiver)\n\t\t}) as T;\n\t}\n\n\t/**\n\t * Intercept a property read, returning a replacement function for a method which should be\n\t * traced, and the value itself for anything else.\n\t * @param target The component being wrapped.\n\t * @param prop The property being read.\n\t * @param receiver The proxy the read was made through.\n\t * @returns The value for the property.\n\t * @internal\n\t */\n\tprivate interceptGet(\n\t\ttarget: { [key: string]: unknown },\n\t\tprop: string | symbol,\n\t\treceiver: unknown\n\t): unknown {\n\t\tconst value = Reflect.get(target, prop, receiver);\n\n\t\tif (!Is.function(value) || !Is.string(prop)) {\n\t\t\treturn value;\n\t\t}\n\n\t\t// Wrapping a synchronous method would make it return a promise. The declaration is tested\n\t\t// rather than the return value, which would open the span too late to nest inner calls.\n\t\tif (Object.prototype.toString.call(value) !== TracingFacade._ASYNC_FUNCTION_TAG) {\n\t\t\treturn value;\n\t\t}\n\n\t\tconst className = this.className(target);\n\n\t\tif (this.matchesAny(this._excludeMethods, [className, prop])) {\n\t\t\treturn value;\n\t\t}\n\n\t\treturn this.tracedMethod(target, className, prop, value);\n\t}\n\n\t/**\n\t * Get the wrapper for a method, building it on first use.\n\t * @param target The component being wrapped.\n\t * @param className The name of the component class.\n\t * @param name The name of the method.\n\t * @param method The method to wrap.\n\t * @returns The wrapper, which is the same function for every read of that method.\n\t * @internal\n\t */\n\tprivate tracedMethod(\n\t\ttarget: { [key: string]: unknown },\n\t\tclassName: string,\n\t\tname: string,\n\t\tmethod: (...args: unknown[]) => unknown\n\t): (...args: unknown[]) => Promise<unknown> {\n\t\tlet wrappers = this._wrappers.get(target);\n\n\t\tif (Is.undefined(wrappers)) {\n\t\t\twrappers = new WeakMap();\n\t\t\tthis._wrappers.set(target, wrappers);\n\t\t}\n\n\t\tlet wrapper = wrappers.get(method);\n\n\t\tif (Is.undefined(wrapper)) {\n\t\t\twrapper = async (...args: unknown[]): Promise<unknown> =>\n\t\t\t\tTracingHelper.withSpan(\n\t\t\t\t\tthis._tracingComponent,\n\t\t\t\t\tIs.stringValue(className) ? `method:${className}.${name}` : `method:${name}`,\n\t\t\t\t\t{ attributes: this.callAttributes(className, name, method, args) },\n\t\t\t\t\tasync span => {\n\t\t\t\t\t\tconst resolved = await method.apply(target, args);\n\n\t\t\t\t\t\tif (!Is.empty(span)) {\n\t\t\t\t\t\t\tconst recorded = this.attributeValue(\n\t\t\t\t\t\t\t\t[className, name, TracingFacade.RESULT_NAME],\n\t\t\t\t\t\t\t\tresolved\n\t\t\t\t\t\t\t);\n\n\t\t\t\t\t\t\tif (!Is.undefined(recorded)) {\n\t\t\t\t\t\t\t\tspan.attributes = {\n\t\t\t\t\t\t\t\t\t...span.attributes,\n\t\t\t\t\t\t\t\t\t[TracingFacadeAttributes.Result]: recorded\n\t\t\t\t\t\t\t\t};\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\treturn resolved;\n\t\t\t\t\t},\n\t\t\t\t\tthis._loggingComponent\n\t\t\t\t);\n\n\t\t\twrappers.set(method, wrapper);\n\t\t}\n\n\t\treturn wrapper;\n\t}\n\n\t/**\n\t * Build the attributes describing a call.\n\t * @param className The name of the component class.\n\t * @param name The name of the method.\n\t * @param method The method being called.\n\t * @param args The arguments the method was called with.\n\t * @returns The attributes.\n\t * @internal\n\t */\n\tprivate callAttributes(\n\t\tclassName: string,\n\t\tname: string,\n\t\tmethod: (...args: unknown[]) => unknown,\n\t\targs: unknown[]\n\t): { [key: string]: unknown } {\n\t\tconst attributes: { [key: string]: unknown } = {\n\t\t\t[TracingFacadeAttributes.Method]: Is.stringValue(className) ? `${className}.${name}` : name\n\t\t};\n\n\t\tconst paramNames = this.paramNames(method);\n\n\t\tfor (let i = 0; i < args.length; i++) {\n\t\t\tconst paramName = paramNames[i];\n\n\t\t\tif (Is.stringValue(paramName)) {\n\t\t\t\tconst recorded = this.attributeValue([className, name, paramName], args[i]);\n\n\t\t\t\tif (!Is.undefined(recorded)) {\n\t\t\t\t\tattributes[`${TracingFacadeAttributes.ParamPrefix}${paramName}`] = recorded;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn attributes;\n\t}\n\n\t/**\n\t * Decide what is recorded for a value, applying the exclusions, the object selection and the\n\t * length limits.\n\t * @param path The class, method and parameter name the value belongs to.\n\t * @param value The value to record.\n\t * @returns The value to record, or undefined when nothing is recorded.\n\t * @internal\n\t */\n\tprivate attributeValue(path: string[], value: unknown): unknown {\n\t\tif (this.matchesAny(this._excludeParams, path)) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tconst primitive = this.primitiveValue(value);\n\n\t\tif (!Is.undefined(primitive)) {\n\t\t\treturn primitive;\n\t\t}\n\n\t\tconst included = this.included(path);\n\n\t\tif (!included.record) {\n\t\t\treturn undefined;\n\t\t}\n\n\t\tif (Is.arrayValue(included.properties)) {\n\t\t\tif (!Is.object<{ [key: string]: unknown }>(value)) {\n\t\t\t\treturn undefined;\n\t\t\t}\n\n\t\t\tconst selected: { [key: string]: unknown } = {};\n\t\t\tfor (const property of included.properties) {\n\t\t\t\tselected[property] = value[property];\n\t\t\t}\n\n\t\t\treturn selected;\n\t\t}\n\n\t\treturn Is.array(value) ? value.slice(0, this._maxArrayLength) : value;\n\t}\n\n\t/**\n\t * Convert a value which can be recorded as a span attribute directly.\n\t * @param value The value to convert.\n\t * @returns The value to record, or undefined when it is not a primitive.\n\t * @internal\n\t */\n\tprivate primitiveValue(value: unknown): unknown {\n\t\tif (Is.string(value)) {\n\t\t\treturn value.length > this._maxStringLength ? value.slice(0, this._maxStringLength) : value;\n\t\t}\n\n\t\t// A bigint cannot be serialised by JSON.stringify, so it is converted here.\n\t\tif (Is.bigint(value)) {\n\t\t\treturn String(value);\n\t\t}\n\n\t\tif (Is.number(value) || Is.boolean(value) || Is.null(value)) {\n\t\t\treturn value;\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * Decide whether a non primitive value is recorded, and which of its properties are.\n\t * @param path The class, method and parameter name the value belongs to.\n\t * @returns Whether to record the value, and the properties to record when the patterns select\n\t * them rather than the whole value.\n\t * @internal\n\t */\n\tprivate included(path: string[]): { record: boolean; properties?: string[] } {\n\t\tconst properties: string[] = [];\n\n\t\tfor (const pattern of this._includeObjects) {\n\t\t\t// The parameter itself is named, so the whole value is recorded.\n\t\t\tif (this.matches(pattern.path, path)) {\n\t\t\t\treturn { record: true };\n\t\t\t}\n\n\t\t\tif (pattern.root.length > 0 && this.matches(pattern.root, path)) {\n\t\t\t\tproperties.push(pattern.last);\n\t\t\t}\n\t\t}\n\n\t\treturn properties.length > 0 ? { record: true, properties } : { record: false };\n\t}\n\n\t/**\n\t * Does any of the patterns match the path.\n\t * @param patterns The patterns to test.\n\t * @param path The path to test them against.\n\t * @returns True when one of the patterns matches.\n\t * @internal\n\t */\n\tprivate matchesAny(patterns: string[][], path: string[]): boolean {\n\t\treturn patterns.some(pattern => this.matches(pattern, path));\n\t}\n\n\t/**\n\t * Does a dot separated pattern match a path. The pattern is matched from the right, so a\n\t * pattern shorter than the path leaves the leading segments unconstrained, and a `*` matches\n\t * any single segment.\n\t * @param segments The segments of the pattern to test.\n\t * @param path The path to test it against.\n\t * @returns True when the pattern matches.\n\t * @internal\n\t */\n\tprivate matches(segments: string[], path: string[]): boolean {\n\t\tif (segments.length > path.length) {\n\t\t\treturn false;\n\t\t}\n\n\t\tconst offset = path.length - segments.length;\n\n\t\treturn segments.every((segment, index) => segment === \"*\" || segment === path[offset + index]);\n\t}\n\n\t/**\n\t * Get the name of the component class, which every IComponent implementation provides.\n\t * @param target The component to get the name of.\n\t * @returns The class name, or an empty string when the component does not provide one.\n\t * @internal\n\t */\n\tprivate className(target: { [key: string]: unknown }): string {\n\t\tconst method = target.className;\n\n\t\tif (Is.function(method)) {\n\t\t\tconst name = method.call(target);\n\n\t\t\tif (Is.stringValue(name)) {\n\t\t\t\treturn name;\n\t\t\t}\n\t\t}\n\n\t\treturn \"\";\n\t}\n\n\t/**\n\t * Get the parameter names of a method, read from its source and held for reuse. An empty list\n\t * is returned when the names cannot be read reliably, so no parameter values are recorded\n\t * rather than being recorded against a name which may be wrong.\n\t * @param method The method to read the parameter names of.\n\t * @returns The parameter names in order, or an empty list when they cannot be trusted.\n\t * @internal\n\t */\n\tprivate paramNames(method: (...args: unknown[]) => unknown): string[] {\n\t\tlet names = this._paramNames.get(method);\n\n\t\tif (Is.undefined(names)) {\n\t\t\tconst source = method.toString();\n\t\t\tconst open = source.indexOf(\"(\");\n\t\t\tconst close = source.indexOf(\")\", open);\n\n\t\t\tnames =\n\t\t\t\topen === -1 || close === -1\n\t\t\t\t\t? []\n\t\t\t\t\t: source\n\t\t\t\t\t\t\t.slice(open + 1, close)\n\t\t\t\t\t\t\t.split(\",\")\n\t\t\t\t\t\t\t.map(param => param.trim())\n\t\t\t\t\t\t\t.filter(param => param.length > 0);\n\n\t\t\t// Anything which is not a plain identifier means the whole list is suspect, so nothing is trusted.\n\t\t\tif (!names.every(name => TracingFacade._IDENTIFIER.test(name))) {\n\t\t\t\tnames = [];\n\t\t\t}\n\n\t\t\tthis._paramNames.set(method, names);\n\t\t}\n\n\t\treturn names;\n\t}\n}\n"]}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./models/ITracingFacadeConfig.js";
+export * from "./models/ITracingFacadeConstructorOptions.js";
+export * from "./models/tracingFacadeAttributes.js";
+export * from "./tracingFacade.js";

package/dist/types/models/ITracingFacadeConfig.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Configuration for the tracing facade.
+ *
+ * The method and parameter patterns are dot separated and matched from the right, so `password`
+ * and `*.*.password` both match a parameter of that name on any method of any class, while
+ * `NotarizationService.create.controllerIdentity` matches only that one. A `*` matches any single
+ * segment.
+ */
+export interface ITracingFacadeConfig {
+    /**
+     * Patterns for parameters whose values are never recorded, whatever their type, matched
+     * against `class.method.parameter`. Supplying this replaces TracingFacade.DEFAULT_EXCLUDE_PARAMS.
+     */
+    excludeParams?: string[];
+    /**
+     * Patterns for methods which are not intercepted at all, matched against `class.method`.
+     * Supplying this replaces TracingFacade.DEFAULT_EXCLUDE_METHODS.
+     */
+    excludeMethods?: string[];
+    /**
+     * Patterns for parameters to record even when the value is not primitive, matched against
+     * `class.method.parameter`. A further segment selects a single property, so
+     * `NotarizationService.create.notarization.mode` records only the mode. Any other non
+     * primitive parameter is not recorded.
+     */
+    includeObjects?: string[];
+    /**
+     * The maximum length of a recorded string, longer values are truncated.
+     * @default 256
+     */
+    maxStringLength?: number;
+    /**
+     * The maximum number of entries recorded for an array.
+     * @default 10
+     */
+    maxArrayLength?: number;
+}

package/dist/types/models/ITracingFacadeConstructorOptions.d.ts

@@ -0,0 +1,19 @@
+import type { ITracingFacadeConfig } from "./ITracingFacadeConfig.js";
+/**
+ * Options for the tracing facade constructor.
+ */
+export interface ITracingFacadeConstructorOptions {
+    /**
+     * The component type for the optional tracing component used for spans. When it does not
+     * resolve the facade passes every call straight through.
+     */
+    tracingComponentType?: string;
+    /**
+     * The component type for the optional logging component, used to report a tracing failure.
+     */
+    loggingComponentType?: string;
+    /**
+     * The configuration for the facade.
+     */
+    config?: ITracingFacadeConfig;
+}

package/dist/types/models/tracingFacadeAttributes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The span attribute keys recorded by the tracing facade.
+ */
+export declare const TracingFacadeAttributes: {
+    /**
+     * The name of the method the span covers.
+     */
+    readonly Method: "method.name";
+    /**
+     * The prefix for the recorded parameter values.
+     */
+    readonly ParamPrefix: "param.";
+    /**
+     * The returned value.
+     */
+    readonly Result: "method.result";
+};
+/**
+ * Union type of all tracing facade attribute string values.
+ */
+export type TracingFacadeAttributes = (typeof TracingFacadeAttributes)[keyof typeof TracingFacadeAttributes];

package/dist/types/tracingFacade.d.ts

@@ -0,0 +1,48 @@
+import { type IFacade } from "@twin.org/core";
+import type { ITracingFacadeConstructorOptions } from "./models/ITracingFacadeConstructorOptions.js";
+/**
+ * Facade which records a span for each external call to an async method on the component it wraps,
+ * so a component can be traced without being modified.
+ *
+ * Only methods declared async are traced. A span cannot be opened synchronously, so wrapping a
+ * synchronous method would make it return a promise and break the contract of the wrapped
+ * component.
+ */
+export declare class TracingFacade implements IFacade {
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * The methods that are excluded from tracing by default.
+     */
+    static readonly DEFAULT_EXCLUDE_METHODS: string[];
+    /**
+     * The parameters that are excluded from recording by default.
+     */
+    static readonly DEFAULT_EXCLUDE_PARAMS: string[];
+    /**
+     * The default maximum length of a recorded string.
+     */
+    static readonly DEFAULT_MAX_STRING_LENGTH: number;
+    /**
+     * The default maximum number of entries recorded for an array.
+     */
+    static readonly DEFAULT_MAX_ARRAY_LENGTH: number;
+    /**
+     * The name a returned value is matched under, so it can be excluded or have a property
+     * selected with the same patterns as a parameter.
+     */
+    static readonly RESULT_NAME: string;
+    /**
+     * Create a new instance of TracingFacade.
+     * @param options The options for the facade.
+     */
+    constructor(options?: ITracingFacadeConstructorOptions);
+    /**
+     * Wrap the target so its method calls are recorded as spans.
+     * @param target The component to wrap.
+     * @returns The wrapped component, or the target itself when there is no tracing component.
+     */
+    wrap<T>(target: T): T;
+}

package/docs/changelog.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.9.3-next.3](https://github.com/iotaledger/twin-tracing/compare/tracing-processors-v0.9.3-next.2...tracing-processors-v0.9.3-next.3) (2026-09-08)
+
+
+### Features
+
+* tracing facade ([#43](https://github.com/iotaledger/twin-tracing/issues/43)) ([83f23ef](https://github.com/iotaledger/twin-tracing/commit/83f23eff032cc8be235ebfb33c5582bfa1c95ddf))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/tracing-models bumped from 0.9.3-next.2 to 0.9.3-next.3
+
+## Changelog

package/docs/examples.md

@@ -0,0 +1,124 @@
+# Tracing Facades Examples
+
+A facade wraps the components a factory produces, so tracing is applied without the component
+being modified. Registering one and activating it on a factory traces everything that factory
+hands out.
+
+## Setup
+
+```typescript
+import { ComponentFactory, FacadeFactory } from '@twin.org/core';
+import { TracingFacade } from '@twin.org/tracing-facades';
+
+FacadeFactory.register(
+  'tracing',
+  () => new TracingFacade({ tracingComponentType: 'tracing', loggingComponentType: 'logging' })
+);
+
+ComponentFactory.useFacade('tracing');
+```
+
+Every component the factory produces from that point on records a span named
+`method:<class>.<name>` for each method called on it. With no tracing component registered the target is returned unwrapped,
+so this is safe to activate unconditionally. A tracing connector which fails does not interrupt
+the call it was recording, and the failure is reported to the logging component when one is
+configured.
+
+## What is recorded
+
+The span carries the method name, the arguments by parameter name, and the returned value when it
+is primitive. A failure records the error message and ends the span with an error status.
+
+```text
+method:NotarizationService.create
+  { "method.name": "NotarizationService.create", "method.result": "urn:..." }
+```
+
+A parameter whose value is not primitive is recorded as present but without its value, so the
+shape of the call is visible without serialising a payload into the trace.
+
+## Keeping values out of a span
+
+Patterns are dot separated and matched from the right, so a bare name applies everywhere and a
+fully qualified one applies to a single method.
+
+```typescript
+config: {
+  excludeParams: [
+    ...TracingFacade.DEFAULT_EXCLUDE_PARAMS,
+    'NotarizationService.create.controllerIdentity'
+  ];
+}
+```
+
+`DEFAULT_EXCLUDE_PARAMS` covers `password`, `token`, `apiKey` and `mnemonic`, and applies when
+`excludeParams` is not supplied. Spread it into a custom list to keep it.
+
+`includeObjects` records a parameter whose value is not primitive. A further segment selects a
+single property, so only that is recorded.
+
+```typescript
+config: {
+  includeObjects: [
+    'NotarizationService.create.notarization.mode',
+    'BlobStorageService.create.options'
+  ];
+}
+```
+
+Any other non primitive parameter is not recorded, so a payload never reaches the trace unless it
+is named.
+
+## Limiting what is recorded
+
+A recorded string is truncated to `maxStringLength`, which defaults to 256, since some methods are
+passed base64 content. An included array is limited to `maxArrayLength` entries, which defaults
+to 10.
+
+```typescript
+config: {
+  maxStringLength: 128,
+  maxArrayLength: 5;
+}
+```
+
+The returned value is recorded under the name `resolved`, so it is excluded or property selected
+with the same patterns.
+
+```typescript
+config: {
+  excludeParams: ['IdentityService.verifiableCredentialCreate.resolved'];
+}
+```
+
+## Methods which are not traced
+
+`excludeMethods` passes the named methods straight through, with no span recorded.
+`DEFAULT_EXCLUDE_METHODS` covers `start`, `stop`, `bootstrap` and `teardown`, the lifecycle
+methods which are called once and carry no request context.
+
+```typescript
+config: {
+  excludeMethods: [...TracingFacade.DEFAULT_EXCLUDE_METHODS, 'IdentityService.identityResolve'];
+}
+```
+
+Only external calls to methods declared `async` are recorded. Opening a span is asynchronous, so
+wrapping a synchronous method would make it return a promise and break the contract of the
+component being wrapped.
+
+## Choosing what gets traced
+
+Facades are activated per factory, so the granularity is yours.
+
+```typescript
+ComponentFactory.useFacade('tracing'); // every service
+EntityStorageConnectorFactory.useFacade('tracing'); // every storage operation
+```
+
+Deactivating applies to instances produced from that point on, since an instance already handed
+out cannot be unwrapped.
+
+```typescript
+ComponentFactory.unuseFacade('tracing');
+```

package/docs/reference/classes/TracingFacade.md

@@ -0,0 +1,113 @@
+# Class: TracingFacade
+
+Facade which records a span for each external call to an async method on the component it wraps,
+so a component can be traced without being modified.
+
+Only methods declared async are traced. A span cannot be opened synchronously, so wrapping a
+synchronous method would make it return a promise and break the contract of the wrapped
+component.
+
+## Implements
+
+- `IFacade`
+
+## Constructors
+
+### Constructor
+
+> **new TracingFacade**(`options?`): `TracingFacade`
+
+Create a new instance of TracingFacade.
+
+#### Parameters
+
+##### options?
+
+[`ITracingFacadeConstructorOptions`](../interfaces/ITracingFacadeConstructorOptions.md)
+
+The options for the facade.
+
+#### Returns
+
+`TracingFacade`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+***
+
+### DEFAULT\_EXCLUDE\_METHODS {#default_exclude_methods}
+
+> `readonly` `static` **DEFAULT\_EXCLUDE\_METHODS**: `string`[]
+
+The methods that are excluded from tracing by default.
+
+***
+
+### DEFAULT\_EXCLUDE\_PARAMS {#default_exclude_params}
+
+> `readonly` `static` **DEFAULT\_EXCLUDE\_PARAMS**: `string`[]
+
+The parameters that are excluded from recording by default.
+
+***
+
+### DEFAULT\_MAX\_STRING\_LENGTH {#default_max_string_length}
+
+> `readonly` `static` **DEFAULT\_MAX\_STRING\_LENGTH**: `number` = `256`
+
+The default maximum length of a recorded string.
+
+***
+
+### DEFAULT\_MAX\_ARRAY\_LENGTH {#default_max_array_length}
+
+> `readonly` `static` **DEFAULT\_MAX\_ARRAY\_LENGTH**: `number` = `10`
+
+The default maximum number of entries recorded for an array.
+
+***
+
+### RESULT\_NAME {#result_name}
+
+> `readonly` `static` **RESULT\_NAME**: `string` = `"resolved"`
+
+The name a returned value is matched under, so it can be excluded or have a property
+selected with the same patterns as a parameter.
+
+## Methods
+
+### wrap() {#wrap}
+
+> **wrap**\<`T`\>(`target`): `T`
+
+Wrap the target so its method calls are recorded as spans.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### target
+
+`T`
+
+The component to wrap.
+
+#### Returns
+
+`T`
+
+The wrapped component, or the target itself when there is no tracing component.
+
+#### Implementation of
+
+`IFacade.wrap`

package/docs/reference/index.md

@@ -0,0 +1,18 @@
+# @twin.org/tracing-facades
+
+## Classes
+
+- [TracingFacade](classes/TracingFacade.md)
+
+## Interfaces
+
+- [ITracingFacadeConfig](interfaces/ITracingFacadeConfig.md)
+- [ITracingFacadeConstructorOptions](interfaces/ITracingFacadeConstructorOptions.md)
+
+## Type Aliases
+
+- [TracingFacadeAttributes](type-aliases/TracingFacadeAttributes.md)
+
+## Variables
+
+- [TracingFacadeAttributes](variables/TracingFacadeAttributes.md)

package/docs/reference/interfaces/ITracingFacadeConfig.md

@@ -0,0 +1,65 @@
+# Interface: ITracingFacadeConfig
+
+Configuration for the tracing facade.
+
+The method and parameter patterns are dot separated and matched from the right, so `password`
+and `*.*.password` both match a parameter of that name on any method of any class, while
+`NotarizationService.create.controllerIdentity` matches only that one. A `*` matches any single
+segment.
+
+## Properties
+
+### excludeParams? {#excludeparams}
+
+> `optional` **excludeParams?**: `string`[]
+
+Patterns for parameters whose values are never recorded, whatever their type, matched
+against `class.method.parameter`. Supplying this replaces TracingFacade.DEFAULT_EXCLUDE_PARAMS.
+
+***
+
+### excludeMethods? {#excludemethods}
+
+> `optional` **excludeMethods?**: `string`[]
+
+Patterns for methods which are not intercepted at all, matched against `class.method`.
+Supplying this replaces TracingFacade.DEFAULT_EXCLUDE_METHODS.
+
+***
+
+### includeObjects? {#includeobjects}
+
+> `optional` **includeObjects?**: `string`[]
+
+Patterns for parameters to record even when the value is not primitive, matched against
+`class.method.parameter`. A further segment selects a single property, so
+`NotarizationService.create.notarization.mode` records only the mode. Any other non
+primitive parameter is not recorded.
+
+***
+
+### maxStringLength? {#maxstringlength}
+
+> `optional` **maxStringLength?**: `number`
+
+The maximum length of a recorded string, longer values are truncated.
+
+#### Default
+
+```ts
+256
+```
+
+***
+
+### maxArrayLength? {#maxarraylength}
+
+> `optional` **maxArrayLength?**: `number`
+
+The maximum number of entries recorded for an array.
+
+#### Default
+
+```ts
+10
+```

package/docs/reference/interfaces/ITracingFacadeConstructorOptions.md

@@ -0,0 +1,28 @@
+# Interface: ITracingFacadeConstructorOptions
+
+Options for the tracing facade constructor.
+
+## Properties
+
+### tracingComponentType? {#tracingcomponenttype}
+
+> `optional` **tracingComponentType?**: `string`
+
+The component type for the optional tracing component used for spans. When it does not
+resolve the facade passes every call straight through.
+
+***
+
+### loggingComponentType? {#loggingcomponenttype}
+
+> `optional` **loggingComponentType?**: `string`
+
+The component type for the optional logging component, used to report a tracing failure.
+
+***
+
+### config? {#config}
+
+> `optional` **config?**: [`ITracingFacadeConfig`](ITracingFacadeConfig.md)
+
+The configuration for the facade.

package/docs/reference/type-aliases/TracingFacadeAttributes.md

@@ -0,0 +1,5 @@
+# Type Alias: TracingFacadeAttributes
+
+> **TracingFacadeAttributes** = *typeof* [`TracingFacadeAttributes`](../variables/TracingFacadeAttributes.md)\[keyof *typeof* [`TracingFacadeAttributes`](../variables/TracingFacadeAttributes.md)\]
+
+Union type of all tracing facade attribute string values.

package/docs/reference/variables/TracingFacadeAttributes.md

@@ -0,0 +1,25 @@
+# Variable: TracingFacadeAttributes
+
+> `const` **TracingFacadeAttributes**: `object`
+
+The span attribute keys recorded by the tracing facade.
+
+## Type Declaration
+
+### Method {#method}
+
+> `readonly` **Method**: `"method.name"` = `"method.name"`
+
+The name of the method the span covers.
+
+### ParamPrefix {#paramprefix}
+
+> `readonly` **ParamPrefix**: `"param."` = `"param."`
+
+The prefix for the recorded parameter values.
+
+### Result {#result}
+
+> `readonly` **Result**: `"method.result"` = `"method.result"`
+
+The returned value.

package/locales/en.json

@@ -0,0 +1 @@
+{}

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@twin.org/tracing-facades",
+	"version": "0.9.3-next.3",
+	"description": "Applies tracing to factory produced components using a facade, without modifying them.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/iotaledger/twin-tracing.git",
+		"directory": "packages/tracing-facades"
+	},
+	"author": "martyn.janes@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"dependencies": {
+		"@twin.org/core": "^0.9.3-next.3",
+		"@twin.org/logging-models": "next",
+		"@twin.org/nameof": "next",
+		"@twin.org/tracing-models": "0.9.3-next.3"
+	},
+	"main": "./dist/es/index.js",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/es/index.js",
+			"default": "./dist/es/index.js"
+		},
+		"./locales/*.json": "./locales/*.json"
+	},
+	"files": [
+		"dist/es",
+		"dist/types",
+		"locales",
+		"docs"
+	],
+	"keywords": [
+		"twin",
+		"trade",
+		"iota",
+		"framework",
+		"blockchain",
+		"tracing",
+		"spans",
+		"facade",
+		"proxy",
+		"instrumentation",
+		"observability"
+	],
+	"bugs": {
+		"url": "git+https://github.com/iotaledger/twin-tracing/issues"
+	},
+	"homepage": "https://twindev.org"
+}