@sailfish-ai/sf-veritas 0.1.32 โ†’ 0.1.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +125 -86
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,119 +1,158 @@
1
- # NextJS Backend Package
1
+ # Sailfish's Backend Data Collector for JavaScript and TypeScript
2
2
 
3
- 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.
3
+ Sailfish's veritas library captures all of the data to enable engineers to properly debug issues.
4
4
 
5
- ## Installation
5
+ ## Supported Frameworks
6
6
 
7
- To install from our repository, you need to configure your `npm` or `yarn` registry settings. Here's how to do it:
7
+ 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):
8
8
 
9
- #### npmrc Configuration
9
+ - Most-widely Used
10
+ - Node.js
11
+ - Next.js
12
+ - Express
13
+ - Angular
14
+ - NestJS
15
+ - NuxtJS
16
+ - Others
17
+ - Apollo Server
18
+ - Mercurius
19
+ - MeteorJS
20
+ - GraphQL over HTTP (formerly Express GraphQL)
10
21
 
11
- ```bash
12
- // Add this to your .npmrc
13
- @sailfishai:registry=https://us-npm.pkg.dev/sailfish-ai/sailfishai-npm/
14
- ```
22
+ ## Installation
15
23
 
16
24
  #### Install the Package
17
25
 
18
- ```bash
19
- npm install --save @sailfish/sf-veritas
20
- # or
21
- yarn add @sailfish/sf-veritas
26
+ Install via your package manager; for reference, here is how you can install our package via `npm` and `yarn`:
27
+
28
+ ```sh title="Install via npm"
29
+ npm install --save @sailfish-ai/sf-veritas
30
+ ```
31
+
32
+ ```sh title="Install via yarn"
33
+ yarn add @sailfish-ai/sf-veritas
22
34
  ```
23
35
 
24
- ## Usage and Example Integration
36
+ ## Integration
25
37
 
26
- ---
38
+ Once you have installed the `sf-veritas` package, it's time to integrate it into your project.
27
39
 
28
- #### Arguments/Parameters
40
+ ### Arguments/Parameters
29
41
 
30
- 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.
42
+ Below are the configuration parameters for `sf-veritas`. These options are passed as an object to the `setupInterceptors` function.
31
43
 
32
- - `serviceIdentifier`: string
44
+ - **`apiKey`**: `string`
33
45
 
34
- - Associates logs with a specific service. Use simple, clear strings for easy identification.
46
+ - This can be seen and copied from your [Settings Configuration page](https://app.sailfishqa.com/settings/configuration) in the "Sailfish Configuration" section.
35
47
 
36
- - `serviceVersion`: string
48
+ - **`serviceIdentifier`**: `string`
37
49
 
38
- - Useful for distinguishing between service versions, particularly in CI/CD environments.
50
+ - This identifies the service that is running.
51
+ - 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.
52
+ - e.g. **`gitOrg`/`gitRepo`/`pathToFile`**
39
53
 
40
- - `serviceAdditionalMetadata`: Record<string, string | number | boolean | null>
54
+ - **`serviceVersion`**: `string`
41
55
 
42
- - Add extra metadata such as cluster information or environment details.
56
+ - This identifies the version of your service - this is a human-readable version and is not required.
57
+
58
+ - **`gitSha`**: `string`
43
59
 
44
- - `domainsToNotPropagateHeadersTo`: string[]
60
+ - 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.
45
61
 
46
- - Prevents adding tracing headers (X-Sf3-Rid) to certain domains.
62
+ - **`serviceAdditionalMetadata`**: `Record<string, string | number | boolean | null>`
63
+
64
+ - Add extra metadata such as cluster information or environment details.
47
65
 
48
- - `nodeModulesToCollectLocalVariablesOn`: string[]
66
+ - **`domainsToNotPropagateHeadersTo`**: `string[]`
49
67
 
50
- - Specify packages or modules for capturing local variable values during errors or exceptions. Use ['__all__'] to capture local variables globally.`
68
+ - Prevents adding tracing headers (`X-Sf3-Rid`) to certain domains.
69
+ - Supports wildcard characters, subdomains, and paths.
51
70
 
52
- #### Example of setup
71
+ - **`nodeModulesToCollectLocalVariablesOn`**: `string[]` (_coming soon_)
72
+ - Specify packages or modules for capturing local variable values during errors or exceptions.
53
73
 
54
- For Next.js projects running on Vercel Edge Functions, there is special **instrumentation.ts|js** file
55
- on which integration should be done. The file should be located in the root directory of the project.
74
+ ### Integration
75
+
76
+ To integrate and start, place the following into your application's entry point, **as early as possible**:
56
77
 
57
78
  ```ts title="JS/TS integration code"
58
- /**
59
- * Initializes instrumentation for both client-side (browser) and server-side (Node.js).
60
- *
61
- * - In **Node.js runtime**, it sets up API interceptors using `setupInterceptors()`
62
- * - In **browser (client-side)**, it starts event recording using `startRecording()`
63
- *
64
- * This ensures that:
65
- * - The correct logic runs based on the environment (client vs. server)
66
- * - There are no runtime errors in unsupported environments
67
- */
68
-
69
- export async function register() {
70
- /**
71
- * โœ… Server-Side (Node.js) Instrumentation
72
- * ---------------------------------------
73
- * - Uses `@sailfish/sf-veritas` to intercept API requests
74
- * - Ensures this logic **only runs on the server**, avoiding client-side errors
75
- */
76
- if (process.env.NEXT_RUNTIME === "nodejs") {
77
- console.log("[Instrumentation] Initializing server-side interceptors...");
78
-
79
- try {
80
- // Dynamically import to ensure it's only loaded in a Node.js environment
81
- const { setupInterceptors } = await import("@sailfish-ai/sf-veritas");
82
-
83
- setupInterceptors({
84
- apiKey: "test-api-key",
85
- serviceIdentifier: "your-service-name",
86
- serviceVersion: "1.0.0",
87
- serviceAdditionalMetadata: {
88
- environment: "production",
89
- cluster: "east-coast",
90
- },
91
- domainsToNotPropagateHeadersTo: ["example.com"],
92
- nodeModulesToCollectLocalVariablesOn: ["@your-org/your-package"],
93
- });
94
-
95
- console.log(
96
- "[Instrumentation] Server-side interceptors initialized successfully.",
97
- );
98
- } catch (error) {
99
- console.error(
100
- "[Instrumentation] Error importing setupInterceptors:",
101
- error,
102
- );
103
- }
104
- }
105
- }
79
+ import { setupInterceptors } from "@sailfish-ai/sf-veritas";
80
+
81
+ setupInterceptors({
82
+ apiKey: "your-api-key",
83
+ serviceIdentifier: "<gitOrg>/<gitRepo>/<pathToFile>",
84
+ domainsToNotPropagateHeadersTo: ["example.com"],
85
+ });
86
+ ```
87
+
88
+ ### Features
89
+
90
+ #### Identify Users
91
+
92
+ 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.
93
+
94
+ #### Identify Signature
95
+
96
+ Here's the argument signature:
97
+
98
+ ```ts
99
+ type Identify = (
100
+ userId: string,
101
+ traits: Record<string, any>,
102
+ override: boolean,
103
+ ) => void;
106
104
  ```
107
105
 
108
- ## Network Hop Summary Statistics
106
+ #### Identify Example
109
107
 
110
- ### ๐Ÿ“Š Response Time Analysis
108
+ 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`.
109
+
110
+ ```ts title="Link a user to a recording"
111
+ import { identify } from "@sailfish-ai/sf-veritas";
112
+
113
+ identify("user-123", { lastAction: "2024-11-18" });
114
+ ```
115
+
116
+ #### Add or Update Metadata
117
+
118
+ 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.
119
+
120
+ - **`userId`**: `string`
121
+
122
+ - This associates the logs (and recording, if there is an associated recording) with a specific user.
123
+
124
+ - **`traits`**: `Record<string, any>`
125
+
126
+ - This is a custom dictionary of traits to values for a specific user or customer. Everything is searchable!
127
+
128
+ - **`traitsJson`**: `string`
129
+
130
+ - This is a custom JSON, just like `traits`, but using the JSON format.
131
+
132
+ - **`override`**: `boolean`
133
+ - This tells whether any of the information we pass along should be overridden or not.
134
+
135
+ #### AddOrUpdateMetadata Signature
136
+
137
+ ```ts
138
+ type AddOrUpdateMetadataFunction = (
139
+ userId: string,
140
+ traits: Record<string, any>,
141
+ override: boolean,
142
+ ) => void;
143
+ ```
144
+
145
+ #### Add/Update Metadata Example
146
+
147
+ ```ts title="Add/Update Metadata for a recording"
148
+ import { addOrUpdateMetadata } from "@sailfish-ai/sf-veritas";
149
+
150
+ addOrUpdateMetadata("user-123", { birthday: "2000-01-01" }, true);
151
+ ```
111
152
 
112
- To evaluate the performance impact of this package, we benchmarked over 1000 HTTP requests with and without the package enabled.
153
+ ### Technical Details
113
154
 
114
- | Configuration | Mean (ms) | Median (ms) | Std Dev (ms) | Requests |
115
- | ------------------ | --------- | ----------- | ------------ | -------- |
116
- | โœ… With Package | 714.17 | 575.00 | 595.92 | 1000 |
117
- | โŒ Without Package | 715.59 | 541.00 | 643.22 | 1000 |
155
+ - **Non-Blocking Execution**: All operations are executed in non-blocking, isolated threads, ensuring less than 20 ยตs of overhead.
156
+ - **Contextual Awareness**: Tracks context across threads, processes, and async tasks to associate logs with the correct sequence of events.
118
157
 
119
- > **Note:** Test results show that the package does not introduce a significant performance slowdown.
158
+ 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!
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sailfish-ai/sf-veritas",
3
- "version": "0.1.32",
3
+ "version": "0.1.33",
4
4
  "publishPublicly": true,
5
5
  "description": "A versatile Edge Runtime-compatible package for Next.js.",
6
6
  "main": "./dist/sf-veritas.cjs",