Advanced Server Settings
This page covers advanced configuration options for the Raphtory Server. For basic server setup, see Running the Server. For a complete list of CLI options, see Command Line Interface.
Logging and Tracing
Raphtory supports OpenTelemetry (OTLP) for distributed tracing, allowing you to monitor and debug query execution in production environments.
Enabling Tracing
To enable tracing, use the --tracing flag when starting the server:
Tracing Levels
Raphtory provides three tracing levels to balance between detail and performance:
| Level | Description |
|---|---|
| MINIMAL | Query summary and execution time only. Best for production monitoring. |
| ESSENTIAL | Tracks key functions (addEdge, addNode, node, edges, etc.) and stores the full query. Useful for monitoring what's broadly happening without performance overhead. |
| COMPLETE | Includes ALL spans for every operation. Use with caution - deep Raphtory queries can generate thousands of spans per query. Excellent for debugging but not suitable for production. |
When running large, deep Raphtory queries with COMPLETE tracing, there can be thousands of spans in a single query. This is invaluable for debugging complex issues but will significantly impact performance. Use ESSENTIAL or MINIMAL for production workloads.
OTLP Configuration
To send traces to an OpenTelemetry collector:
Log Levels
Control the verbosity of server logs with --log-level:
Available levels: trace, debug, info, warn, error
Caching
The server maintains a cache for frequently accessed graphs:
--cache-capacity: Maximum number of graphs to keep in cache--cache-tti-seconds: Time-to-idle in seconds before a cached graph is evicted
Authentication
Raphtory supports JWT-based authentication for securing your GraphQL API using EdDSA (Ed25519) keys.
Generating Keys
Generate an Ed25519 key pair using OpenSSL:
Access Levels
JWT tokens must include an a claim specifying access level:
"a": "ro"- Read-only access (queries only)"a": "rw"- Read-write access (queries and mutations)
Server Configuration
Start the server with authentication enabled:
Or with auth_enabled_for_reads=False to allow unauthenticated reads (auth required only for writes).
Complete Example
Without a valid token, authenticated endpoints will return a 401 error. Read tokens cannot perform write operations.
Configuration File
Instead of passing all options via CLI, you can use a TOML configuration file:
Example config.toml
CLI arguments take precedence over config file settings, allowing you to override specific options at startup.