Skip to content

Commit 8d0d2b6

Browse files
quantstruct-botquantstruct-bot
committed
Final evals for generated guides
1 parent a51eb7f commit 8d0d2b6

8 files changed

Lines changed: 220 additions & 47 deletions

‎mint.json‎

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -53,29 +53,43 @@
5353
"kubernetes"
5454
]
5555
},
56-
"benchmarks"
56+
"benchmarks",
57+
{
58+
"group": "Troubleshooting",
59+
"icon": "hammer",
60+
"pages": [
61+
"troubleshooting-guide"
62+
]
63+
}
5764
]
5865
},
5966
{
6067
"group": "Tutorials",
6168
"pages": [
6269
{
63-
"group": "Using the dashboard",
70+
"group": "Use the dashboard",
6471
"icon": "chart-column",
6572
"pages": [
6673
"request-graph",
6774
"adding-filter-clauses"
6875
]
76+
},
77+
{
78+
"group": "Filter traffic to Subtrace",
79+
"icon": "filter",
80+
"pages": [
81+
"proxy-rules-guide"
82+
]
6983
}
7084
]
7185
},
7286
{
7387
"group": "References",
7488
"pages": [
75-
"references/subtrace-run-doc",
76-
"references/subtrace-proxy-doc",
77-
"references/subtrace-worker-doc",
78-
"references/subtrace-version-doc"
89+
"references/subtrace-run",
90+
"references/subtrace-proxy",
91+
"references/subtrace-worker",
92+
"references/subtrace-version"
7993
]
8094
}
8195
],

‎proxy-rules-guide.mdx‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
title: "Writing Rules for Subtrace Proxy"
3+
description: "Learn how to use the subtrace proxy command to control which HTTP traffic is traced"
4+
lastUpdated: "2024-12-17"
5+
---
6+
# Writing Rules for Subtrace Proxy: A Beginner's Guide
7+
8+
## Introduction
9+
10+
When running subtrace proxy to monitor your HTTP traffic, you may not want to trace every single request - some might be too noisy (like health checks), while others may contain sensitive data. Subtrace lets you control this using JavaScript rules.
11+
12+
## Basic Setup
13+
14+
First, let's set up a basic proxy that forwards traffic from port 8080 to our API running on port 3000:
15+
16+
```bash
17+
# Create a rules file
18+
touch rules.js
19+
20+
# Start the proxy
21+
subtrace proxy \
22+
-listen localhost:8080 \
23+
-remote localhost:3000 \
24+
-config rules.js
25+
```
26+
27+
## Writing Your First Rule
28+
29+
Rules are written using the `trace()` function. Let's start with a simple rule that traces all requests:
30+
31+
```javascript
32+
// rules.js
33+
trace("*", "*", function() {
34+
return true;
35+
});
36+
```
37+
38+
The `trace()` function takes three arguments:
39+
1. HTTP method pattern (like "GET", "POST", "*" for all)
40+
2. Path pattern (like "/api/users", "/health", "*" for all)
41+
3. A function that returns true to trace the request, false to ignore it
42+
43+
## Building More Specific Rules
44+
45+
Let's build rules for our ecommerce API. We want to:
46+
- Trace all product-related requests
47+
- Skip health checks
48+
- Sample only 10% of static asset requests
49+
- Always trace error responses
50+
51+
```javascript
52+
// rules.js
53+
54+
// Trace all product-related endpoints
55+
trace("*", "/api/products/*", function() {
56+
return true;
57+
});
58+
59+
// Skip health checks completely
60+
trace("GET", "/health", function() {
61+
return false;
62+
});
63+
64+
// Sample 10% of static asset requests
65+
trace("GET", "/static/*", {
66+
sample: 0.1
67+
});
68+
69+
// Trace any request that returns an error
70+
trace("*", "*", function(req, resp) {
71+
return resp.statusCode >= 400;
72+
});
73+
```
74+
75+
## Pattern Matching
76+
77+
The method and path patterns support:
78+
- Exact matches: "GET", "/api/users"
79+
- Wildcards: "*" matches anything
80+
- Suffixes: "/api/*" matches any path starting with /api/
81+
82+
## Adding Conditions
83+
84+
You can make more complex decisions in your rule functions. Let's expand our example:
85+
86+
```javascript
87+
// rules.js
88+
89+
// Trace slow requests that take > 500ms
90+
trace("*", "*", function(req, resp) {
91+
return req.duration > 500;
92+
});
93+
94+
// Trace requests with specific header
95+
trace("POST", "/api/*", function(req) {
96+
return req.headers["x-trace-this"] === "true";
97+
});
98+
99+
// Combine multiple conditions
100+
trace("PUT", "/api/orders/*", function(req, resp) {
101+
return resp.statusCode >= 400 || // Error responses
102+
req.duration > 1000 || // Slow requests
103+
req.body.priority === "high"; // High priority orders
104+
});
105+
```
106+
107+
## Rule Evaluation Order
108+
109+
Rules are evaluated in the order they appear in your file. Once a rule matches and returns true, that decision is final. Use this to create precedence:
110+
111+
```javascript
112+
// rules.js
113+
114+
// First, skip health checks unconditionally
115+
trace("GET", "/health", () => false);
116+
117+
// Then apply sampling to everything else
118+
trace("*", "*", { sample: 0.1 });
119+
```
120+
121+
## Reference
122+
123+
Common patterns:
124+
125+
```javascript
126+
// Match specific HTTP methods
127+
trace("GET", "...")
128+
trace("POST", "...")
129+
trace("PUT", "...")
130+
trace("DELETE", "...")
131+
132+
// Match paths
133+
trace("*", "/exact/path")
134+
trace("*", "/api/*") // Everything under /api
135+
trace("*", "*.jpg") // All jpg files
136+
trace("*", "/users/*/posts") // Match /users/123/posts
137+
138+
// Sampling
139+
trace("*", "*", { sample: 0.5 }) // 50% of requests
140+
141+
// Access request/response info
142+
trace("*", "*", function(req, resp) {
143+
req.method // HTTP method
144+
req.path // Request path
145+
req.headers // Request headers
146+
req.body // Request body
147+
req.duration // Request duration in ms
148+
149+
resp.statusCode // Response status code
150+
resp.headers // Response headers
151+
resp.body // Response body
152+
})
153+
```
154+
155+
## Best Practices
156+
157+
1. Start with broad rules and refine them
158+
2. Use sampling for high-volume endpoints
159+
3. Always skip health check endpoints
160+
4. Put most specific rules first
161+
5. Use meaningful patterns that map to your API structure
162+
6. Don't overload your rules with complex logic
163+
7. Monitor the impact of your rules on system performance
164+
165+
The key is to find the right balance between visibility and performance for your specific use case. Start simple and iterate based on your needs.

‎quickstart.mdx‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,6 @@ icon: "rocket"
3333
<img className="rounded-xl" src="/quickstart-2-token.png" />
3434

3535
**Step 4**: Install the latest version of Subtrace, set the `SUBTRACE_TOKEN` environment variable to the **tracer token** you generated in step 3, and use `subtrace run` to start your app.
36-
<AccordionGroup>
3736
<CodeGroup>
3837
```bash bash
3938
# replace amd64 with arm64 if applicable
@@ -86,16 +85,13 @@ icon: "rocket"
8685
print(f"Request failed as expected: {e}")
8786
```
8887
</CodeGroup>
89-
<Accordion title="What does the `--` mean?">
90-
The `--` is a [bash builtin command](https://www.gnu.org/software/bash/manual/html_node/Bash-Builtins.html) that is used to indicate that all arguments after it are treated as a command to run, not as arguments for `subtrace run`.
91-
</Accordion>
92-
</AccordionGroup>
93-
88+
The double dash (`--`) is required to separate subtrace flags from the command you want to run (read more in the [subtrace run reference](/references/subtrace-run-doc#usage)).
89+
9490
**Step 5** *(optional)*: Add the Subtrace executable to your `$PATH` so you can run `subtrace` from anywhere.
95-
- Check if `/usr/local/bin` exists in your `$PATH`. If it doesn't exist, create it.
91+
- Validate that `/usr/local/bin` exists in your `$PATH`.
9692
<CodeGroup>
9793
```bash bash
98-
echo $PATH && sudo mkdir -p /usr/local/bin
94+
echo $PATH
9995
```
10096
```bash output
10197
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

references/subtrace-proxy-doc.mdx renamed to references/subtrace-proxy.mdx

Lines changed: 14 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: 'Proxy Command'
2+
title: 'subtrace proxy'
33
description: 'Learn how to use the subtrace proxy command to trace HTTP traffic through a reverse proxy'
44
---
55

@@ -51,26 +51,9 @@ Enable verbose logging:
5151
subtrace proxy -v -listen :8080 -remote api.example.com
5252
```
5353

54-
## Configuration File
54+
## Writing Rules in a Configuration File
5555

56-
The proxy supports JavaScript-based rules for filtering requests. Create a file like `rules.js`:
57-
58-
```javascript
59-
// Trace only 10% of GET requests to /api
60-
trace("GET", "/api/*", {
61-
sample: 0.1
62-
})
63-
64-
// Don't trace health checks
65-
trace("GET", "/health", function() {
66-
return false
67-
})
68-
69-
// Trace all POST requests
70-
trace("POST", "*", function() {
71-
return true
72-
})
73-
```
56+
Refer to the [Proxy Rules Guide](/proxy-rules-guide) guide for more information on how to write rules.
7457

7558
## Environment Variables
7659

@@ -132,14 +115,16 @@ error: listen tcp :8080: bind: address already in use
132115

133116
## Security Considerations
134117

135-
- Proxy can see all HTTP traffic
118+
- Proxy can see all HTTP traffic (unless you use rules to filter)
136119
- TLS interception requires trust configuration
137120
- Consider network access controls
138121
- Protect configuration files
139122
- Sanitize sensitive headers
140123

141124
## Example Configuration Patterns
142125

126+
Refer to the [Proxy Rules Guide](/proxy-rules-guide) guide for more example configurations on how to write rules.
127+
143128
### Basic Load Balancer
144129

145130
```javascript
@@ -163,9 +148,14 @@ trace("*", "*", function(req, resp) {
163148
})
164149
```
165150

151+
## Related Commands
152+
153+
- [`subtrace run`](/references/subtrace-run-doc) - Run a process with tracing enabled
154+
- [`subtrace worker`](/references/subtrace-worker-doc) - Start a worker node (for self-hosted setups)
155+
- [`subtrace version`](/references/subtrace-version-doc) - Show version information
156+
166157
## Additional Resources
167158

168159
- [Subtrace Documentation](https://docs.subtrace.dev)
169-
- [Proxy Configuration Guide](https://docs.subtrace.dev/proxy/config)
170-
- [Rule Writing Guide](https://docs.subtrace.dev/proxy/rules)
171-
- [Security Best Practices](https://docs.subtrace.dev/security)
160+
- [Proxy Rule Writing Guide](/proxy-rules-guide)
161+
{/* - [Security Best Practices](https://docs.subtrace.dev/security) */}

references/subtrace-run-doc.mdx renamed to references/subtrace-run.mdx

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@ The `subtrace run` command allows you to trace HTTP traffic from any application
1111
subtrace run [flags] -- <command> [arguments]
1212
```
1313

14-
The double dash (`--`) is required to separate subtrace flags from the command you want to run.
14+
<Accordion title="What does the `--` mean?">
15+
The `--` is a [bash builtin command](https://www.gnu.org/software/bash/manual/html_node/Bash-Builtins.html) that is used to indicate that all arguments after it are treated as a command to run, not as arguments for `subtrace run`.
16+
</Accordion>
1517

1618
## Flags
1719

@@ -133,7 +135,7 @@ time="2024-03-14T15:04:05Z" event_id="550e8400-e29b-41d4-a716-446655440000" http
133135

134136
## Related Commands
135137

136-
- `subtrace proxy` - Run a reverse proxy with tracing
137-
- `subtrace version` - Show version information
138-
- `subtrace worker` - Start a worker node (for self-hosted setups)
138+
- [`subtrace proxy`](/references/subtrace-proxy-doc) - Run a reverse proxy with tracing
139+
- [`subtrace version`](/references/subtrace-version-doc) - Show version information
140+
- [`subtrace worker`](/references/subtrace-worker-doc) - Start a worker node (for self-hosted setups)
139141

references/subtrace-version-doc.mdx renamed to references/subtrace-version.mdx

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,3 +82,9 @@ The version command is commonly used for troubleshooting purposes:
8282
- Capability flags are only shown on Linux systems
8383
- JSON output can be particularly useful for integration with other tools
8484
- All timestamps are in UTC
85+
86+
## Related Commands
87+
88+
- [`subtrace run`](/references/subtrace-run-doc) - Run a process with tracing enabled
89+
- [`subtrace proxy`](/references/subtrace-proxy-doc) - Start a reverse proxy with tracing
90+
- [`subtrace worker`](/references/subtrace-worker-doc) - Start a worker node (for self-hosted setups)

references/subtrace-worker-doc.mdx renamed to references/subtrace-worker.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: 'subtrace workedr'
2+
title: 'subtrace worker'
33
description: 'The worker command starts a Subtrace worker node that processes and stores trace data in ClickHouse.'
44
---
55

@@ -126,6 +126,6 @@ For production environments:
126126

127127
## Related Commands
128128

129-
- `subtrace run` - Run a process with tracing enabled
130-
- `subtrace proxy` - Start a reverse proxy with tracing
131-
- `subtrace version` - Show version information
129+
- [`subtrace run`](/references/subtrace-run-doc) - Run a process with tracing enabled
130+
- [`subtrace proxy`](/references/subtrace-proxy-doc) - Start a reverse proxy with tracing
131+
- [`subtrace version`](/references/subtrace-version-doc) - Show version information

‎troubleshooting-guide.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,7 @@ subtrace run -- your_application
157157
- Higher resource usage
158158

159159
### Root Cause
160-
Subtrace adds monitoring overhead, though it's designed to be minimal (<0.1ms in typical cases).
160+
Subtrace adds monitoring overhead, though it's designed to be minimal (< 0.1ms in typical cases).
161161

162162
### Solutions
163163

0 commit comments

Comments
 (0)