Skip to content

Commit bd94b5c

Browse files
jy-tanjy-tan
authored
chore: update README and docs (#23)
1 parent 68984dd commit bd94b5c

6 files changed

Lines changed: 294 additions & 278 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 278 deletions
Original file line numberDiff line numberDiff line change
@@ -31,304 +31,38 @@ If you're using packages or versions not listed above, please create an issue wi
3131

3232
## Installation
3333

34-
### Step 1: CLI Setup
34+
### Step 1: Install the CLI
3535

36-
First, install and configure the Tusk Drift CLI by following our [CLI installation guide](https://github.com/Use-Tusk/tusk-drift-cli?tab=readme-ov-file#install).
36+
First, install and configure the Tusk Drift CLI by following our [CLI installation guide](https://github.com/Use-Tusk/tusk-drift-cli?tab=readme-ov-file#install). The CLI helps set up your Tusk configuration file and replays tests.
3737

3838
The wizard will eventually direct you back here when it's time to set up the SDK.
3939

40-
### Step 2: SDK Installation
40+
### Step 2: Install the SDK
4141

4242
After completing the CLI wizard, install the SDK:
4343

4444
```bash
4545
npm install @use-tusk/drift-node-sdk
4646
```
4747

48-
## Initialization
48+
### Step 3: Initialize the SDK for your service
4949

50-
### Prerequisites
50+
Refer to our [initialization guide](docs/initialization.md) to set up the SDK for your service.
5151

52-
Before setting up the SDK, ensure you have:
52+
### Step 4: Run Your First Test
5353

54-
- Completed the [CLI wizard](https://github.com/Use-Tusk/tusk-drift-cli?tab=readme-ov-file#quick-start)
55-
- Obtained an API key from the [Tusk Drift dashboard](https://usetusk.ai/app/settings/api-keys) (only required if using Tusk Cloud)
56-
57-
Follow these steps in order to properly initialize the Tusk Drift SDK:
58-
59-
### 1. Create SDK Initialization File
60-
61-
Create a separate file (e.g. `tuskDriftInit.ts`) to initialize the Tusk Drift SDK. This ensures the SDK is initialized as early as possible before any other modules are loaded.
62-
63-
**IMPORTANT**: Ensure that `TuskDrift` is initialized before any other telemetry providers (e.g. OpenTelemetry, Sentry, etc.). If not, your existing telemetry may not work properly.
64-
65-
#### For CommonJS Applications
66-
67-
```typescript
68-
// tuskDriftInit.ts
69-
import { TuskDrift } from "@use-tusk/drift-node-sdk";
70-
71-
// Initialize SDK immediately
72-
TuskDrift.initialize({
73-
apiKey: process.env.TUSK_DRIFT_API_KEY,
74-
env: process.env.NODE_ENV,
75-
});
76-
77-
export { TuskDrift };
78-
```
79-
80-
#### For ESM Applications
81-
82-
ESM applications require additional setup to properly intercept module imports:
83-
84-
```typescript
85-
// tuskDriftInit.ts
86-
import { register } from 'node:module';
87-
import { pathToFileURL } from 'node:url';
88-
89-
// Register the ESM loader
90-
// This enables interception of ESM module imports
91-
register('@use-tusk/drift-node-sdk/hook.mjs', pathToFileURL('./'));
92-
93-
import { TuskDrift } from "@use-tusk/drift-node-sdk";
94-
95-
// Initialize SDK immediately
96-
TuskDrift.initialize({
97-
apiKey: process.env.TUSK_DRIFT_API_KEY,
98-
env: process.env.NODE_ENV,
99-
});
100-
101-
export { TuskDrift };
102-
```
103-
104-
**Why the ESM loader is needed**: ESM imports are statically analyzed and hoisted, meaning all imports are resolved before any code runs. The `register()` call sets up Node.js loader hooks that intercept module imports, allowing the SDK to instrument packages like `postgres`, `http`, etc. Without this, the SDK cannot patch ESM modules.
105-
106-
#### Configuration Options
107-
108-
<table>
109-
<thead>
110-
<tr>
111-
<th>Option</th>
112-
<th>Type</th>
113-
<th>Default</th>
114-
<th>Description</th>
115-
</tr>
116-
</thead>
117-
<tbody>
118-
<tr>
119-
<td><code>apiKey</code></td>
120-
<td><code>string</code></td>
121-
<td><b>Required if using Tusk Cloud</b></td>
122-
<td>Your Tusk Drift API key.</td>
123-
</tr>
124-
<tr>
125-
<td><code>env</code></td>
126-
<td><code>string</code></td>
127-
<td><code>process.env.NODE_ENV</code></td>
128-
<td>The environment name.</td>
129-
</tr>
130-
<tr>
131-
<td><code>logLevel</code></td>
132-
<td><code>'silent' | 'error' | 'warn' | 'info' | 'debug'</code></td>
133-
<td><code>'info'</code></td>
134-
<td>The logging level.</td>
135-
</tr>
136-
</tbody>
137-
</table>
138-
139-
### 2. Import SDK at Application Entry Point
140-
141-
#### For CommonJS Applications
142-
143-
In your main server file (e.g., `server.ts`, `index.ts`, `app.ts`), require the initialized SDK **at the very top**, before any other requires:
144-
145-
```typescript
146-
// server.ts
147-
import { TuskDrift } from "./tuskDriftInit"; // MUST be the first import
148-
149-
// ... other imports ...
150-
151-
// Your application setup...
152-
```
153-
154-
> **IMPORTANT**: Ensure NO require calls are made before requiring the SDK initialization file. This guarantees proper instrumentation of all dependencies.
155-
156-
#### For ESM Applications
157-
158-
For ESM applications, you **cannot** control import order within your application code because all imports are hoisted. Instead, use the `--import` flag:
159-
160-
**Update your package.json scripts**:
161-
162-
```json
163-
{
164-
"scripts": {
165-
"dev": "node --import ./dist/tuskDriftInit.js dist/server.js",
166-
"dev:record": "TUSK_DRIFT_MODE=RECORD node --import ./dist/tuskDriftInit.js dist/server.js"
167-
}
168-
}
169-
```
170-
171-
**Why `--import` is required for ESM**: In ESM, all `import` statements are hoisted and evaluated before any code runs, making it impossible to control import order within a file. The `--import` flag ensures the SDK initialization (including loader registration) happens in a separate phase before your application code loads, guaranteeing proper module interception.
172-
173-
### 3. Update Configuration File
174-
175-
Update the configuration file `.tusk/config.yaml` to include a `recording` section. Example `recording` configuration:
176-
177-
```yaml
178-
# ... existing configuration ...
179-
180-
recording:
181-
sampling_rate: 0.1
182-
export_spans: true
183-
enable_env_var_recording: true
184-
```
185-
186-
#### Configuration Options
187-
188-
<table>
189-
<thead>
190-
<tr>
191-
<th>Option</th>
192-
<th>Type</th>
193-
<th>Default</th>
194-
<th>Description</th>
195-
</tr>
196-
</thead>
197-
<tbody>
198-
<tr>
199-
<td><code>sampling_rate</code></td>
200-
<td><code>number</code></td>
201-
<td><code>1.0</code></td>
202-
<td>The sampling rate (0.0 - 1.0). 1.0 means 100% of requests are recorded, 0.0 means 0% of requests are recorded.</td>
203-
</tr>
204-
<tr>
205-
<td><code>export_spans</code></td>
206-
<td><code>boolean</code></td>
207-
<td><code>false</code></td>
208-
<td>Whether to export spans to Tusk backend or local files (<code>.tusk/traces</code>). If false, spans are only exported to local files.</td>
209-
</tr>
210-
<tr>
211-
<td><code>enable_env_var_recording</code></td>
212-
<td><code>boolean</code></td>
213-
<td><code>false</code></td>
214-
<td>Whether to enable environment variable recording and replaying. Recommended if your application's business logic depends on environment variables, as this ensures the most accurate replay behavior.</td>
215-
</tr>
216-
</tbody>
217-
</table>
218-
219-
### 4. Mark App as Ready
220-
221-
Once your application has completed initialization (database connections, middleware setup, etc.), mark it as ready:
222-
223-
```typescript
224-
// server.ts
225-
import { TuskDrift } from "./tuskDriftInit";
226-
227-
// ... other imports ...
228-
229-
const app = express();
230-
231-
// Your application setup...
232-
233-
app.listen(8000, () => {
234-
// Mark app as ready for recording/replay
235-
TuskDrift.markAppAsReady();
236-
console.log("Server started and ready for Tusk Drift");
237-
});
238-
```
239-
240-
## Run Your First Test
241-
242-
Let's walk through recording and replaying your first trace:
243-
244-
### Step 1: Set sampling rate to 1.0
245-
246-
Set the `sampling_rate` in `.tusk/config.yaml` to 1.0 to ensure that all requests are recorded.
247-
248-
### Step 2: Start server in record mode
249-
250-
Run your server in record mode using the `TUSK_DRIFT_MODE` environment variable:
251-
252-
```bash
253-
TUSK_DRIFT_MODE=RECORD node server.js
254-
```
255-
256-
You should see logs indicating Tusk Drift is active:
257-
258-
```
259-
[TuskDrift] SDK initialized in RECORD mode
260-
[TuskDrift] App marked as ready
261-
```
262-
263-
### Step 3: Generate Traffic
264-
265-
Make a request to a simple endpoint that includes some database and/or network calls:
266-
267-
```bash
268-
curl http://localhost:8000/api/test/weather
269-
```
270-
271-
### Step 4: Stop Recording
272-
273-
Wait for a few seconds and then stop your server with `Ctrl+C`. This will give time for traces to be exported.
274-
275-
### Step 5: List Recorded Traces
276-
277-
In your project directory, list the recorded traces:
278-
279-
```bash
280-
tusk list
281-
```
282-
283-
You should see output similar to:
284-
285-
<img src="images/tusk-list-output.png">
286-
287-
Press `ESC` to exit the list view.
288-
289-
Need to install the Tusk CLI? See [CLI installation guide](https://github.com/Use-Tusk/tusk-drift-cli?tab=readme-ov-file#install).
290-
291-
### Step 6: Replay the Trace
292-
293-
Replay the recorded test:
294-
295-
```bash
296-
tusk run
297-
```
298-
299-
You should see output similar to:
300-
301-
<img src="images/tusk-run-output.png">
302-
303-
**Success!** You've recorded and replayed your first trace.
54+
Follow along our [quick start guide](docs/quickstart.md) to record and replay your first test!
30455

30556
## Troubleshooting
30657

307-
### Common Issues
308-
309-
#### No traces being recorded
310-
311-
1. **Check sampling rate**: Ensure `sampling_rate` in `.tusk/config.yaml` is 1.0
312-
2. **Verify app readiness**: Make sure you're calling `TuskDrift.markAppAsReady()`
313-
3. **Use debug mode in SDK**: Add `logLevel: 'debug'` to the initialization parameters
314-
315-
#### Existing telemetry not working
316-
317-
Ensure that `TuskDrift.initialize()` is called before any other telemetry providers (e.g. OpenTelemetry, Sentry, etc.).
318-
319-
#### Replay failures
320-
321-
1. **Enable service and CLI logs**:
322-
323-
```bash
324-
tusk run --debug
325-
```
58+
Having issues?
32659

327-
Logs will be written to `.tusk/logs/`
60+
- Read our [troubleshooting doc](docs/troubleshooting.md)
61+
- Create an issue or reach us at [support@usetusk.ai](mailto:support@usetusk.ai).
32862

329-
2. **Test with simple endpoint**: Start with endpoints that only return static data
63+
## Contributing
33064

331-
3. **Check dependencies**: Verify you're using supported package versions
65+
We appreciate feedback and contributions. See [CONTRIBUTING.md](/CONTRIBUTING.md).
33266

33367
## License
33468

0 commit comments

Comments
 (0)