@rivetkit/engine 1.0.0

package/contrib-docs/ACTOR_KEY_RESERVATION.md

@@ -0,0 +1,101 @@
+# Actor Key Reservation
+
+Epoxy is used to globally store which datacenter an actor lives in for a given actor ID.
+
+## Schema
+
+In Epoxy KV store: `Actor key -> reservation ID`
+
+The reservation ID includes the datacenter of where the actor lives.
+
+## Consistency Limitations
+
+Actors have 2 touch points with Epoxy:
+
+- Reserve actor key (epaxos fast path = 1 RTT, epaxos slow path = 2 RTT)
+- Resolve actor ID for key (fast path = 0 RTT, slow path = 1 RTT to nearest DC that has the key)
+
+Resolving actor ID uses `kv_get_optimistic`, which assumes a value does not change after being set. This allows us to cache the actor's datacenter locally and never have to read from other nodes once we've resolved it once.
+
+## Reservation ID
+
+A reservation ID is a unique ID (which includes the datacenter label).
+
+**Why not store the actor ID**
+
+Actor IDs initially make sense to use since they include the datacenter ID that the actor lives in.
+
+Actor IDs can be created and destroyed, but our consistency limitations above requires that we do not change the value after set. Therefore, because we cannot update keys to new actor IDs, we cannot store the actor ID.
+
+**Why not store just the datacenter label**
+
+A naiive approach would be to store just the datacenter label in epoxy where the actor lives.
+
+See reservation chains below.
+
+### Reservation Chains & Moving Reservation Datacenters (Future Work)
+
+Eventually, actors need to be moved between datacenters OR destroyed then create in a different datacenter. 
+
+To do this, we'll set up reservation ID chains. Reservation ID chains are used to resolve where a reservation was moved to. When attempting to resolve a reservation that was moved, that datacenter will return the pointer to the reservation that it was moved to.
+
+Consider:
+
+- Actor 1 created in DC A with key "foo"
+	- Generates reservation ID X (in DC A)
+	- Epoxy stores: foo = reservation X
+- Actor 1 destroyed
+- Actor 2 created in DC B with key "foo"
+	- Generations reservation ID Y (in DC B)
+	- DC A stores pointer from reservation X to reservation Y
+	- Epoxy still has: foo = reservation X (does not get updated)
+- Next request to key "foo":
+	- Read reservation ID X (in DC A) from Epoxy
+	- Client send request to DC A with reservation ID X
+	- DC A returns pointer to reservation ID Y (in DC B)
+		- Client caches this pointer
+	- Client sends request to DC B with reservation ID Y
+- If the client requests key "foo" again:
+	- Read reservation ID X (in DC A) from Epoxy
+	- Client reads cache for reservation X to reservation Y (in DC B)
+	- Sends request to DC B
+
+The resulting state is:
+
+```
+Epoxy:
+- foo = reservation X (in DC A)
+
+Pointer cache (DC A):
+- Reservation X (in DC A) -> reservation Y (in DC B)
+```
+
+**Why not just use datacenter label**
+
+Consider a chain of pointers between the following datacenters:
+
+```
+DC label: 1 -> 2 -> 1 -> 3
+Pointer:    A    B    C
+```
+
+There is a race condition & possible infinite loop when:
+
+- DC 2 has pointer to DC 1 (pointer B)
+- DC 1 still has pointer to DC 2 (pointer A) (has not updated to DC 3, pointer C)
+
+Using unique reservation IDs allow us to create IDs like `{dc}.{unique}`. The chain would look like:
+
+```
+Reservation ID: 1.1 -> 2.2 -> 1.3 -> 3.4
+Pointer:            A      B      C
+```
+
+Now there cannot be a loop between DC 1 & 2 since clients will follow the chain of pointers.
+
+_This section needs more elaboration on edge cases._
+
+## Current Limitation: Keys are tied to a datacenter
+
+Because we cannot change the value of the reservation ID, actors can only be created in the original for a given ID.
+

package/contrib-docs/API.md

@@ -0,0 +1,11 @@
+# API
+
+## Packages
+
+- `packages/common/api-types`:
+    - `src/{}/mod.rs`: Common API types shared between multiple packages.
+    - `src/{}/{}.rs`: Request types used in api-peer (e.g. `get`, `list`). This is not in `rivet-api-peer` because these types must be used with `rivet-api-client` in packaes that don't depend ont `rivet-api-peer` (often because of cirular dependency issues, e.g. `rivet-api-peer` -> `pegboard` -> `rivet-api-peer`)
+- `packages/common/api-client`: Helper utilities for making requests to `api-peer`
+- `packages/common/api-builder`: Helper utilities for building API servers with Axum
+- `packages/services/api-peer`: API endpoint used for peer-to-peer communication across datacenters, only used by internal Rivet packages
+- `packages/services/api-public`: API endpoints used by clients calling Rivet APIs

package/contrib-docs/DOCKER.md

@@ -0,0 +1,5 @@
+# Runner Docker Compose
+
+`docker compose -f ../docker/dev/docker-compose.yml up --build`
+
+> Sometimes adding `--force-recreate` is required to get it to deploy the new build

package/contrib-docs/ERRORS.md

@@ -0,0 +1,13 @@
+# Errors
+
+## RivetError
+
+TODO: Document the derive macro
+TODO: Document .build() -> anyhow
+
+## Error chains
+
+- TODO: use `.chain().filter_map(|x| x.downcast_ref::<T>())` otherwise it'll only check the top-most error
+- TODO: use `#[source]` in thiserror variants in order for wrapped errors to show up in `.chain()`
+- TODO: `#[from]` automatically adds `#[source]`
+

package/contrib-docs/GUARD.md

@@ -0,0 +1,76 @@
+# Guard Routing & Retry Behavior
+
+## Guard Core - Retry Behavior
+
+The retry mechanism enables optimistic routing with cache invalidation:
+
+- **Fast path with cached routes**: Guard uses cached routing information to avoid expensive database lookups on every request, providing low-latency routing decisions
+- **Graceful cache invalidation**: When actors are stopped, destroyed, or moved to different runners, the cache becomes stale. Rather than proactively invalidating cache entries (which would require complex coordination), any failure response signals that the cached route is invalid
+- **Fresh service discovery on retry**: Retry attempts ignore the cache and perform fresh database lookups to discover current actor locations, ensuring requests reach the correct destination
+
+This approach optimizes for the common case (actors are running and routes are valid) while gracefully handling the uncommon case (actors have moved/stopped) without sacrificing performance
+
+### Retry Flow
+
+**Initial Request (Attempt 1)**:
+
+1. Check route cache for target location
+2. If cached route exists, send request to cached target
+3. If request succeeds → return response to client
+4. If request fails with retry-able error → proceed to retry
+
+**Retry Attempts (Attempts 2-N)**:
+
+1. Wait for exponential backoff delay (100ms × 2^(attempt-2))
+2. **Ignore cache** and perform fresh database lookup for target location
+3. Send request to newly discovered target
+4. If request succeeds → return response to client
+5. If request fails and max attempts not reached → repeat retry flow
+6. If max attempts exceeded → return `502 Bad Gateway` to client
+
+**Configuration**:
+
+- **Exponential backoff**: Starting interval 100ms, doubles each attempt (100ms, 200ms, 400ms...)
+- **Maximum attempts**: Default 3 total attempts
+- **Retry triggers**: TCP connection errors OR `503 Service Unavailable` with `x-rivet-error` header
+
+### Expected Service Response for Retries
+
+Services that want to trigger guard retries must respond with:
+
+- `503 Service Unavailable` status code
+- `x-rivet-error: <error>` header
+
+## Guard Router - Routing Logic
+
+### Routing Priority
+
+Requests are routed in the following priority order:
+
+#### 1. Target-Based Routing (Header: `x-rivet-target`)
+
+When the `x-rivet-target` header is present, routes to specific service types:
+
+**Actor Services** (`x-rivet-target: actor`):
+- **Required headers**: 
+  - `x-rivet-actor: <actor_id>` - UUID of the specific actor instance
+- **Optional headers**:
+  - `x-rivet-addr: <address>` - Direct address override for actor location
+- **Behavior**: Routes to the specific actor instance, with cross-datacenter routing if the actor resides in a different DC
+
+**Runner** (`x-rivet-target: runner`):
+- **Purpose**: Routes WebSocket connections to the Pegboard runner service
+- **Target**: Routes to the configured Pegboard service (`pegboard.lan_host:pegboard.port`)
+- **Use case**: WebSocket connections between runners and the orchestration system
+
+#### 2. API Routing (No target header)
+
+When no `x-rivet-target` header is present:
+- **Target**: Routes to the public API service (`api_public.lan_host:api_public.port`)
+- **Behavior**: Standard HTTP API requests for general application functionality
+- **Path preservation**: The original request path is preserved in the upstream request
+
+#### 3. Fallback
+
+Returns `404 Not Found` if no routing rules match.
+

package/contrib-docs/PEGBOARD_TUNNEL_RETRIES.md

@@ -0,0 +1,83 @@
+# Pegboard Tunnel Retries
+
+_TODO: Clean up this AI slop explanation_
+
+This document explains how retries are coordinated between Guard and Pegboard-based handlers when transient tunnel (UPS) issues occur, for both HTTP and WebSocket traffic.
+
+## HTTP
+
+- Signal: A retryable transient tunnel failure is signaled by returning an HTTP 503 with the `X-RIVET-ERROR` header set.
+  - Example (Pegboard Gateway): on tunnel closed (e.g., UPS `request_timeout`), the gateway replies with `503` and `X-RIVET-ERROR: pegboard_gateway.tunnel_closed`.
+
+- Guard behavior
+  - Guard considers a response retryable if `status == 503` and the `X-RIVET-ERROR` header is present.
+  - Guard then applies exponential backoff (from middleware-config: `max_attempts`, `initial_interval`), re-resolves the route with `ignore_cache = true`, and retries the request.
+  - On successful retry, traffic proceeds normally to the new target.
+  - If attempts are exhausted, Guard returns an upstream error to the client.
+
+- Notes for implementers
+  - For transient tunnel failures, return a 503 with `X-RIVET-ERROR` to trigger Guard retries. Use an empty body or minimal payload as appropriate.
+  - Do not 503 for non-transient errors; let the normal error flow apply.
+
+## WebSocket
+
+This section explains how WebSocket retries are coordinated between Guard and Pegboard-based handlers.
+
+## Overview
+
+- Retries are only possible before the client WebSocket is accepted ("opening" stage).
+- A retryable transient failure is signaled via the error `guard.websocket_service_unavailable` (WebSocketServiceUnavailable).
+- When Guard receives this error during opening, it re-resolves routes (ignoring cache), applies backoff, and retries with the same client socket and a new handler if available.
+- After the client socket is accepted ("open"), retries are not possible; the handler must close gracefully on failure.
+
+### Lifecycle Behavior
+
+- Opening (before accept)
+  - Source: handler detects a transient UPS/tunnel issue before awaiting the `HyperWebsocket` (e.g., failing to `ups.request(...)` to open, or failing to `ups.subscribe(...)`).
+  - Handler contract:
+    - Do not await the client websocket yet.
+    - Return the untouched `HyperWebsocket` in the error tuple so Guard still owns it: `Err((client_ws, err))`.
+    - The outer wrapper maps tunnel-closed UPS errors (e.g., `ups.request_timeout`) to `WebSocketServiceUnavailable`.
+  - Guard reaction:
+    - Treats `WebSocketServiceUnavailable` as retryable.
+    - Re-resolves the route with ignore-cache=true, using middleware-config retry/backoff.
+    - Outcomes:
+      - Re-resolve → `CustomServe`: reuse the same `client_ws` and retry with the new handler.
+      - Re-resolve → `Response`: accept client, send a Close with the response message as the reason.
+      - Re-resolve → `Target` (non-CustomServe) or mismatch: accept client, send a Close with a generic message (cannot retry).
+      - Attempts exhausted: accept client and send a Close with the original error message.
+
+- Open (after accept)
+  - The handler has awaited the client websocket; Guard can no longer retry.
+  - Any failures (UPS send/receive, serialization, etc.) should be handled by closing the connection gracefully.
+
+- Closing
+  - Best-effort signaling to the server via `ups.request(...)` and to the client via Close frames.
+  - Failures are ignored; no retries.
+
+- Closed
+  - No further action.
+
+### Implementer Guidance
+
+- Keep the client socket intact for retries:
+  - Only return a retryable error (that maps to `WebSocketServiceUnavailable`) before awaiting the client websocket.
+  - Return the socket in the error tuple: `Err((client_ws, err))`.
+
+- Map tunnel-closed errors at the wrapper:
+  - In the outer `handle_websocket` wrapper, detect tunnel-closed (e.g., `ups.request_timeout`) and map to `WebSocketServiceUnavailable`.
+  - `handle_websocket_inner` should return raw errors; do not construct `WebSocketServiceUnavailable` inside the inner function.
+
+- Use `ups.request` for all tunnel operations (open, messages, close):
+  - Pre-accept failures should surface as errors with the unconsumed `client_ws` so Guard can retry.
+  - Post-accept failures should break streams and close gracefully; do not attempt retries.
+
+- Backoff and attempts:
+  - Guard uses middleware-config values for `max_attempts` and `initial_interval` to perform exponential backoff between retries.
+  - Routes are re-resolved with ignore-cache=true on each retry to avoid stale targets.
+
+### Rationale
+
+- Returning the untouched `HyperWebsocket` in errors preserves the ability for Guard to re-route and retry without disconnecting the client.
+- Mapping tunnel-closed conditions to a single sentinel error (`WebSocketServiceUnavailable`) provides a consistent, guard-specific signal for retryability.
+- Restricting retries to pre-accept avoids protocol violations and simplifies resource ownership.

package/contrib-docs/RUNNER_LIFECYCLE.md

@@ -0,0 +1,172 @@
+# Runner Lifecycle
+
+## Connection
+
+```mermaid
+sequenceDiagram
+	participant R as Runner
+	participant P as Pegboard
+	participant RW as Runner Workflow
+
+	note over R,RW: Phase 1: WebSocket Connection
+
+	R->>P: WebSocket open
+	R->>P: ToServerInit (name, version, totalSlots, lastCommandIdx)
+	note over R: start ping interval (3s)
+	note over R: start command ack interval (5min)
+
+	P->>RW: Forward (ToServerInit)
+	note over RW: ProcessInit activity
+	note over RW: load state, process prepopulated actors
+
+	note over R,RW: Phase 2: Initialize Runner
+
+	RW->>P: ToClientInit (runnerId, lastEventIdx, metadata)
+	P->>R: ToClientInit
+
+	note over R: store runnerId
+	note over R: store runnerLostThreshold from metadata
+
+	note over R,RW: Phase 3: Resend Pending State
+
+	note over R: processUnsentKvRequests
+	note over R: resendUnacknowledgedEvents
+	note over R: tunnel.resendBufferedEvents
+
+	note over R,RW: Phase 4: Send Missed Commands
+
+	RW->>P: ToClientCommands (missed commands)
+	P->>R: ToClientCommands
+	note over R: handleCommands
+
+	note over R,RW: Phase 5: Complete Connection
+
+	note over RW: InsertDb activity
+	note over RW: write runner to database
+	note over RW: update allocation indexes
+
+	note over R: config.onConnected callback
+```
+
+## Reconnect
+
+```mermaid
+sequenceDiagram
+	participant R as Runner
+	participant P as Pegboard
+	participant RW as Runner Workflow
+
+	note over R,RW: Phase 1: Detect Disconnection
+
+	alt WebSocket error/close
+		P--xR: connection lost
+		note over R: start runner lost timeout (if threshold configured)
+		note over R: schedule reconnect with backoff
+		note over R: config.onDisconnected callback
+	end
+
+	note over R,RW: Phase 2: Reconnect
+
+	note over R: calculate backoff delay
+	note over R: increment reconnectAttempt counter
+
+	R->>P: WebSocket open (reconnect)
+	R->>P: ToServerInit (lastCommandIdx preserved)
+
+	note over R: clear reconnect timeout
+	note over R: clear runner lost timeout
+	note over R: reset reconnectAttempt = 0
+
+	P->>RW: Forward (ToServerInit)
+	RW->>P: ToClientInit (lastEventIdx)
+	P->>R: ToClientInit
+
+	note over R,RW: Phase 3: Resynchronize
+
+	note over R: if runnerId changed, clear event history
+
+	note over R: processUnsentKvRequests
+	note over R: resendUnacknowledgedEvents (from lastEventIdx)
+	note over R: tunnel.resendBufferedEvents
+
+	alt missed commands exist
+		RW->>P: ToClientCommands (missed commands)
+		P->>R: ToClientCommands
+		note over R: handleCommands
+	end
+
+	note over R: config.onConnected callback
+```
+
+## Shutdown
+
+```mermaid
+sequenceDiagram
+	participant R as Runner
+	participant P as Pegboard
+	participant RW as Runner Workflow
+	participant A as Actors
+
+	note over R,RW: Phase 1: Initiate Shutdown
+
+	alt graceful shutdown
+		R->>P: ToServerStopping
+		P->>RW: Forward (ToServerStopping)
+	else forced stop
+		RW->>RW: receive Stop signal
+	end
+
+	note over R,RW: Phase 2: Drain Runner
+
+	note over RW: handle_stopping
+	note over RW: set state.draining = true
+	note over RW: ClearDb activity (update_state = Draining)
+	note over RW: remove from allocation indexes
+	note over RW: set drain_ts, expired_ts
+
+	note over RW: FetchRemainingActors activity
+	loop for each actor
+		RW->>A: GoingAway signal
+		note over A: actor workflows begin stopping
+	end
+
+	note over R,RW: Phase 3: Wait for Actors
+
+	note over R: waitForActorsToStop (max 120s)
+	loop check every 100ms
+		alt all actors stopped
+			note over R: continue shutdown
+		else websocket closed
+			note over R: force continue shutdown
+		else timeout reached
+			note over R: force continue shutdown
+		end
+	end
+
+	note over R,RW: Phase 4: Close WebSocket
+
+	note over R: send ToServerStopping (if not sent)
+	R->>P: WebSocket close (code=1000, reason=pegboard.runner_shutdown)
+	note over R: clear ping interval
+	note over R: clear ack interval
+	note over R: tunnel.shutdown
+
+	note over R: config.onShutdown callback
+
+	note over R,RW: Phase 5: Complete Workflow
+
+	note over RW: workflow exits drain loop after runner_lost_threshold
+
+	note over RW: ClearDb activity (update_state = Stopped)
+	note over RW: remove from active indexes
+	note over RW: set stop_ts
+
+	note over RW: FetchRemainingActors activity
+	loop for each remaining actor
+		RW->>A: Lost signal
+		note over A: reschedule actors if needed
+	end
+
+	RW->>P: ToClientClose
+	note over RW: workflow complete
+```

package/contrib-docs/SDKS.md

@@ -0,0 +1,9 @@
+# Generating SDKs
+
+To make sure the openapi spec is up to date, run `cargo check -p rivet-dump-openapi`
+
+Use `./scripts/fern/gen.sh` to generate the SDKs, which will be outputted under `sdks/api`
+
+# Endpoints
+
+A current list of API endpoints can be found at `packages/core/api-public/src/router.rs` or in the `out/openapi.json` file. 

package/contrib-docs/TEST_DEPENDENCIES.md

@@ -0,0 +1,43 @@
+# Test Dependencies
+
+The `rivet-test-deps` package provides isolated test environments with configurable database and pub/sub backends.
+
+## Configuration
+
+Configure backends via environment variables:
+
+- `RIVET_TEST_DATABASE`: Choose database backend
+  - `foundationdb` - Runs FoundationDB in Docker
+  - `postgres` - PostgreSQL in Docker
+  - `filesystem` - RocksDB with temp directory (default)
+
+- `RIVET_TEST_PUBSUB`: Choose pub/sub backend
+  - `nats` - Runs NATS in Docker
+  - `postgres_notify` - PostgreSQL in Docker
+  - `memory` - In-memory channels (default)
+
+- `RUST_LOG`: Enable debug logs to see container lifecycle details
+	- For example, `RUST_LOG=debug` will enable more verbose logs
+
+## How It Works
+
+1. **Port Selection**: Automatically picks unused ports for all services
+2. **Container Management**: 
+   - Starts Docker containers for services that require them
+   - Each test gets unique container names using UUIDs
+   - Containers are automatically cleaned up on drop
+3. **Config Generation**: Creates a complete Rivet config with the selected backends
+4. **Isolation**: Each test instance gets isolated resources (unique channels, temp dirs, containers)
+
+## Usage
+
+```rust
+let deps = TestDeps::new().await?;
+// Use deps.pools() and deps.config() for your tests
+// Containers are cleaned up automatically when deps is dropped
+```
+
+For multi-datacenter tests:
+```rust
+let deps = TestDeps::new_multi(&[1, 2, 3]).await?;
+```

package/contrib-docs/design-choicse/EMBEDDED_KV.md

@@ -0,0 +1,80 @@
+# Embedded KV
+
+## Goals
+
+- Embedded (no need for multi-process)
+- Similarity to FDB in transacations
+- Supports high write throughput
+
+## Decision
+
+Chose RocksDB because:
+
+- It's stable & boring
+- Supports high write throughput
+
+Nice to haves:
+
+- Better compression on disk
+
+## Evaluation
+
+### RocksDB
+
+Uses LSM trees. Requires backgound compaction. Has a lot of overhead to work like a "real" database.
+
+Pros:
+
+- Supports a WAL for logging & buffering writes
+
+Cons:
+
+- Significantly more complicated
+- Overhead of background threads managing compaction
+- Does not provide native MVCC + conflict ranges, we must re-implement this ourselves
+
+### LMDB
+
+Uses B+ tree for storage. mmaps database.
+
+**The critical downside of LMDB is that performance suffers under write-heavy workoads from (a) single writer locks and (b) uses mmap instead of buffering writes.**
+
+Pros:
+
+- Simple implementation
+- Very little overhead
+
+Cons:
+
+- No compaction
+- Single writer lock
+- Transaction commits each have an fsync, while RocksDB can optimize with a WAL + batching writes
+- Uses pages with mmap which is slower than using a WAL + batching writes
+- Does not work well with small writes since it's copied at the page level (Rivet is almost all small writes)
+
+### sled, redb, fjall
+
+All three differe significantly, but the primary reason for disqualifying these is maturity. Sled claims to be "beta" and not mature yet, while redb and fjall claim to have a stable disk format.
+
+**This is not a place we need to innovate, so it makes more sense to go with an established embedded KV.**
+
+Pros:
+
+- Rust-native
+	- Less potential issues with building & linking
+	- Theoretically faster compilation than RocksDB
+
+### SQLite
+
+This would be the simplest & most straightforward option in terms of support. FDB's pre-7.0 storage engine is based on the SQLite's B-tree implementation.
+
+**SQLite provides overhead we don't need when options like RocksDB or LMDB exist.**
+
+Pros:
+
+- Widely supported, no issues with building it
+- We already have a deep experience with SQLite
+
+## Resources
+
+- https://github.com/marvin-j97/rust-storage-bench

package/contrib-docs/operate/TRACING_RECONFIGURE.md

@@ -0,0 +1,78 @@
+# Dynamic Tracing Configuration
+
+Dynamically reconfigure log levels and OpenTelemetry sampling for all running services without restart.
+
+## Log Filter Configuration
+
+Control which log messages are displayed by setting filter directives (similar to `RUST_LOG`).
+
+**Set log filter to debug**
+
+```bash
+rivet-engine tracing config -f debug
+
+# Or via HTTP API:
+curl -X PUT http://localhost:6421/debug/tracing/config \
+  -H "Content-Type: application/json" \
+  -d '{"filter":"debug"}'
+```
+
+**Debug a specific package**
+
+```bash
+rivet-engine tracing config -f "debug,rivet_api_peer=trace"
+
+# Or via HTTP API:
+curl -X PUT http://localhost:6421/debug/tracing/config \
+  -H "Content-Type: application/json" \
+  -d '{"filter":"debug,rivet_api_peer=trace"}'
+```
+
+**Reset log filter to defaults**
+
+```bash
+rivet-engine tracing config -f ""
+
+# Or via HTTP API:
+curl -X PUT http://localhost:6421/debug/tracing/config \
+  -H "Content-Type: application/json" \
+  -d '{"filter":null}'
+```
+
+## OpenTelemetry Sampler Ratio
+
+Control what percentage of traces are sampled and sent to the OpenTelemetry collector.
+
+**Set sampler ratio to 10%**
+
+```bash
+rivet-engine tracing config -s 0.1
+
+# Or via HTTP API:
+curl -X PUT http://localhost:6421/debug/tracing/config \
+  -H "Content-Type: application/json" \
+  -d '{"sampler_ratio":0.1}'
+```
+
+**Set sampler ratio to 100% (capture all traces)**
+
+```bash
+rivet-engine tracing config -s 1.0
+
+# Or via HTTP API:
+curl -X PUT http://localhost:6421/debug/tracing/config \
+  -H "Content-Type: application/json" \
+  -d '{"sampler_ratio":1.0}'
+```
+
+**Reset sampler ratio to default**
+
+```bash
+rivet-engine tracing config -s 0.001
+
+# Or via HTTP API:
+curl -X PUT http://localhost:6421/debug/tracing/config \
+  -H "Content-Type: application/json" \
+  -d '{"sampler_ratio":null}'
+```
+

package/docker/dev/.gitattributes

@@ -0,0 +1 @@
+. linguist-generated=true