@sailfish-ai/sf-veritas 0.1.30 → 0.1.33

package/README.md

@@ -1,119 +1,158 @@
-# NextJS Backend Package
+# Sailfish's Backend Data Collector for JavaScript and TypeScript
 
-Middleware for JavaScript and TypeScript to intercept and log API requests, console outputs, and exceptions, while persisting trace data for frameworks such as Next.js, Nuxt.js and more.
+Sailfish's veritas library captures all of the data to enable engineers to properly debug issues.
 
-## Installation
+## Supported Frameworks
 
-To install from our repository, you need to configure your `npm` or `yarn` registry settings. Here's how to do it:
+As of September 2025, we support [the most widely-used JS/TS backend frameworks](https://survey.stackoverflow.co/2025/technology#most-popular-technologies-webframe) and others (in both JavaScript and TypeScript):
 
-#### npmrc Configuration
+- Most-widely Used
+  - Node.js
+  - Next.js
+  - Express
+  - Angular
+  - NestJS
+  - NuxtJS
+- Others
+  - Apollo Server
+  - Mercurius
+  - MeteorJS
+  - GraphQL over HTTP (formerly Express GraphQL)
 
-```bash
-// Add this to your .npmrc
-@sailfishai:registry=https://us-npm.pkg.dev/sailfish-ai/sailfishai-npm/
-```
+## Installation
 
 #### Install the Package
 
-```bash
-npm install --save @sailfish/sf-veritas
-# or
-yarn add @sailfish/sf-veritas
+Install via your package manager; for reference, here is how you can install our package via `npm` and `yarn`:
+
+```sh title="Install via npm"
+npm install --save @sailfish-ai/sf-veritas
+```
+
+```sh title="Install via yarn"
+yarn add @sailfish-ai/sf-veritas
 ```
 
-## Usage and Example Integration
+## Integration
 
----
+Once you have installed the `sf-veritas` package, it's time to integrate it into your project.
 
-#### Arguments/Parameters
+### Arguments/Parameters
 
-1. Below are the configuration parameters for @sailfish/sf-veritas. These options are passed as an object to the setupInterceptors function. All parameters are non-mandatory.
+Below are the configuration parameters for `sf-veritas`. These options are passed as an object to the `setupInterceptors` function.
 
-- `serviceIdentifier`: string
+- **`apiKey`**: `string`
 
-  - Associates logs with a specific service. Use simple, clear strings for easy identification.
+  - This can be seen and copied from your [Settings Configuration page](https://app.sailfishqa.com/settings/configuration) in the "Sailfish Configuration" section.
 
-- `serviceVersion`: string
+- **`serviceIdentifier`**: `string`
 
-  - Useful for distinguishing between service versions, particularly in CI/CD environments.
+  - This identifies the service that is running.
+  - The value is extremely important because Sailfish uses the `serviceIdentifier` to link sevices to the location in code. Without this, Sailfish can have issues locating code and automatically fixing issues.
+    - e.g. **`gitOrg`/`gitRepo`/`pathToFile`**
 
-- `serviceAdditionalMetadata`: Record<string, string | number | boolean | null>
+- **`serviceVersion`**: `string`
 
-  - Add extra metadata such as cluster information or environment details.
+  - This identifies the version of your service - this is a human-readable version and is not required.
+
+- **`gitSha`**: `string`
 
-- `domainsToNotPropagateHeadersTo`: string[]
+  - This is the Git SHA of your releases - populating this via this argument or an environment variable helps your team tie issues to code changes quickly.
 
-  - Prevents adding tracing headers (X-Sf3-Rid) to certain domains.
+- **`serviceAdditionalMetadata`**: `Record<string, string | number | boolean | null>`
+
+  - Add extra metadata such as cluster information or environment details.
 
-- `nodeModulesToCollectLocalVariablesOn`: string[]
+- **`domainsToNotPropagateHeadersTo`**: `string[]`
 
-  - Specify packages or modules for capturing local variable values during errors or exceptions. Use ['__all__'] to capture local variables globally.`
+  - Prevents adding tracing headers (`X-Sf3-Rid`) to certain domains.
+    - Supports wildcard characters, subdomains, and paths.
 
-#### Example of setup
+- **`nodeModulesToCollectLocalVariablesOn`**: `string[]` (_coming soon_)
+  - Specify packages or modules for capturing local variable values during errors or exceptions.
 
-For Next.js projects running on Vercel Edge Functions, there is special **instrumentation.ts|js** file
-on which integration should be done. The file should be located in the root directory of the project.
+### Integration
+
+To integrate and start, place the following into your application's entry point, **as early as possible**:
 
 ```ts title="JS/TS integration code"
-/**
- * Initializes instrumentation for both client-side (browser) and server-side (Node.js).
- *
- * - In **Node.js runtime**, it sets up API interceptors using `setupInterceptors()`
- * - In **browser (client-side)**, it starts event recording using `startRecording()`
- *
- * This ensures that:
- * - The correct logic runs based on the environment (client vs. server)
- * - There are no runtime errors in unsupported environments
- */
-
-export async function register() {
-  /**
-   * ✅ Server-Side (Node.js) Instrumentation
-   * ---------------------------------------
-   * - Uses `@sailfish/sf-veritas` to intercept API requests
-   * - Ensures this logic **only runs on the server**, avoiding client-side errors
-   */
-  if (process.env.NEXT_RUNTIME === "nodejs") {
-    console.log("[Instrumentation] Initializing server-side interceptors...");
-
-    try {
-      // Dynamically import to ensure it's only loaded in a Node.js environment
-      const { setupInterceptors } = await import("@sailfish-ai/sf-veritas");
-
-      setupInterceptors({
-        apiKey: "test-api-key",
-        serviceIdentifier: "your-service-name",
-        serviceVersion: "1.0.0",
-        serviceAdditionalMetadata: {
-          environment: "production",
-          cluster: "east-coast",
-        },
-        domainsToNotPropagateHeadersTo: ["example.com"],
-        nodeModulesToCollectLocalVariablesOn: ["@your-org/your-package"],
-      });
-
-      console.log(
-        "[Instrumentation] Server-side interceptors initialized successfully.",
-      );
-    } catch (error) {
-      console.error(
-        "[Instrumentation] Error importing setupInterceptors:",
-        error,
-      );
-    }
-  }
-}
+import { setupInterceptors } from "@sailfish-ai/sf-veritas";
+
+setupInterceptors({
+  apiKey: "your-api-key",
+  serviceIdentifier: "<gitOrg>/<gitRepo>/<pathToFile>",
+  domainsToNotPropagateHeadersTo: ["example.com"],
+});
+```
+
+### Features
+
+#### Identify Users
+
+You can also associate data (logs, exceptions, and network requests) with specific users using the identify method. This is particularly helpful for user-centric debugging.
+
+#### Identify Signature
+
+Here's the argument signature:
+
+```ts
+type Identify = (
+  userId: string,
+  traits: Record<string, any>,
+  override: boolean,
+) => void;
 ```
 
-## Network Hop Summary Statistics
+#### Identify Example
 
-### 📊 Response Time Analysis
+In order to identify, you will need to call the `identify` method. You can also force an override of stored values by setting the `override` argument to `true`.
+
+```ts title="Link a user to a recording"
+import { identify } from "@sailfish-ai/sf-veritas";
+
+identify("user-123", { lastAction: "2024-11-18" });
+```
+
+#### Add or Update Metadata
+
+In order to add or update metadata associated with specific users and the recordings, you can use the `addOrUpdateMetadata` method. This will associate all information with the recording by calling this method on any Node.js backend.
+
+- **`userId`**: `string`
+
+  - This associates the logs (and recording, if there is an associated recording) with a specific user.
+
+- **`traits`**: `Record<string, any>`
+
+  - This is a custom dictionary of traits to values for a specific user or customer. Everything is searchable!
+
+- **`traitsJson`**: `string`
+
+  - This is a custom JSON, just like `traits`, but using the JSON format.
+
+- **`override`**: `boolean`
+  - This tells whether any of the information we pass along should be overridden or not.
+
+#### AddOrUpdateMetadata Signature
+
+```ts
+type AddOrUpdateMetadataFunction = (
+  userId: string,
+  traits: Record<string, any>,
+  override: boolean,
+) => void;
+```
+
+#### Add/Update Metadata Example
+
+```ts title="Add/Update Metadata for a recording"
+import { addOrUpdateMetadata } from "@sailfish-ai/sf-veritas";
+
+addOrUpdateMetadata("user-123", { birthday: "2000-01-01" }, true);
+```
 
-To evaluate the performance impact of this package, we benchmarked over 1000 HTTP requests with and without the package enabled.
+### Technical Details
 
-| Configuration      | Mean (ms) | Median (ms) | Std Dev (ms) | Requests |
-| ------------------ | --------- | ----------- | ------------ | -------- |
-| ✅ With Package    | 714.17    | 575.00      | 595.92       | 1000     |
-| ❌ Without Package | 715.59    | 541.00      | 643.22       | 1000     |
+- **Non-Blocking Execution**: All operations are executed in non-blocking, isolated threads, ensuring less than 20 µs of overhead.
+- **Contextual Awareness**: Tracks context across threads, processes, and async tasks to associate logs with the correct sequence of events.
 
-> **Note:** Test results show that the package does not introduce a significant performance slowdown.
+By following these steps, you can seamlessly integrate `sf-veritas` into your Node.js project and start capturing LEaPS (Logs, Exceptions, and Print Statements) effectively!