Catch the highlights of GraphQLConf 2023! Click for recordings. Or check out our recap blog post.
Documentation
Configuration
General

Configuration File

This section describes the top-level configuration object for Conductor gateway.

Conductor supports both YAML and JSON format for the configuration file.

Loading the config file

The configuration is loaded when server starts, based on the runtime environment you are using:

Binary

If you are running the Conductor binary directly, you can specify the configuration file path using the first argument:

 
conductor my-config-file.json
 

By default, Conductor will look for a file named config.json in the current directory.

Docker

If you are using Docker environment, you can mount the configuration file into the container, and then point the Conductor binary to it:

 
docker run -v my-config-file.json:/app/config.json the-guild-org/conductor:latest /app/config.json
 

CloudFlare Worker

WASM runtime doesn’t allow filesystem access, so you need to load the configuration file into an environment variable named CONDUCTOR_CONFIG.

Autocomplete/validation in VSCode

For JSON files, you can specify the $schema property to enable autocomplete and validation in VSCode:

config.json
 
{ "$schema": "https://raw.githubusercontent.com/the-guild-org/conductor/master/libs/config/conductor.schema.json" }
 

For YAML auto-complete and validation, you can install the YAML Language Support extension and enable it by adding the following to your YAML file:

config.yaml
 
$schema: "https://raw.githubusercontent.com/the-guild-org/conductor/master/libs/config/conductor.schema.json"
 

JSONSchema

As part of the release flow of Conductor, we are publishing the configuration schema as a JSONSchema file.

You can find here the latest version of the schema.

Configuration Interpolation with Environment Variables

This feature allows the dynamic insertion of environment variables into the config file for Conductor. It enhances flexibility by adapting the configuration based on the runtime environment.

Syntax for Environment Variable Interpolation: - Use ${VAR_NAME} to insert the value of an environment variable. If VAR_NAME is not set, an error will pop up. - Specify a default value with ${VAR_NAME:default_value} which is used when VAR_NAME is not set. - Escape a dollar sign by preceding it with a backslash (e.g., \$) to use it as a literal character instead of triggering interpolation.

Examples: - endpoint: ${API_ENDPOINT:https://api.example.com/} - Uses the API_ENDPOINT variable or defaults to the provided URL. - name: \$super - Results in the literal string name: \$super in the configuration.

Configuration

Reference

server
optional

Configuration for the HTTP server.

port
integer
default: 9000

The port to listen on, default to 9000

host
string
default: "127.0.0.1"

The host to listen on, default to 127.0.0.1

logger
optional

Conductor logger configuration.

filter
string
default: "info"

Environment filter configuration as a string. This allows extremely powerful control over Conductor’s logging.

The filter can specify various directives to filter logs based on module paths, span names, and specific fields. These directives can also be combined using commas as a separator.

Basic Usage:

  • info (logs all messages at info level and higher across all modules)

  • error (logs all messages at error level only, as it’s the highest level of severity)

Module-Specific Logging:

  • conductor::gateway=debug (logs all debug messages for the ‘conductor::gateway’ module)

  • conductor::engine::source=trace (logs all trace messages for the ‘conductor::engine::source’ module)

Combining Directives:

  • conductor::gateway=info,conductor::engine::source=trace (sets info level for the gateway module and trace level for the engine’s source module)

The syntax of directives is very flexible, allowing complex logging configurations.

See tracing_subscriber::EnvFilter for more information.

format
default: "pretty"

Configured the logger format. See options below.

  • pretty format is human-readable, ideal for development and debugging.

  • json format is structured, suitable for production environments and log analysis tools.

By default, pretty is used in TTY environments, and json is used in non-TTY environments.

The following options are valid for this field:
compact

This logging format outputs minimal, compact logs. It focuses on the essential parts of the log message and its fields, making it suitable for production environments where performance and log size are crucial.

Pros:

  • Efficient in terms of space and performance.

  • Easy to read for brief messages and simple logs.

Cons:

  • May lack detailed context, making debugging a bit more challenging.
pretty

The pretty format is designed for enhanced readability, featuring more verbose output including well-formatted fields and context. Ideal for development and debugging purposes.

Pros:

  • Highly readable and provides detailed context.

  • Easier to understand complex log messages.

Cons:

  • More verbose, resulting in larger log sizes.

  • Potentially slower performance due to the additional formatting overhead.

json

This format outputs logs in JSON. It is particularly useful when integrating with tools that consume or process JSON logs, such as log aggregators and analysis systems.

Pros:

  • Structured format makes it easy to parse and integrate with various tools.

  • Consistent and predictable output.

Cons:

  • Can be verbose and harder to read directly by developers.

  • Slightly more overhead compared to simpler formats like compact.

print_performance_info
boolean
default: false

Emits performance information on in crucial areas of the gateway.

Look for close and idle spans printed in the logs.

Note: this option is not enabled on WASM runtime, and will be ignored if specified.

sources
array
required

List of sources to be used by the gateway. Each source is a GraphQL endpoint or multiple endpoints grouped using a federated implementation.

For additional information, please refer to the Sources section.

endpoints
array
required

List of GraphQL endpoints to be exposed by the gateway. Each endpoint is a GraphQL schema that is backed by one or more sources and can have a unique set of plugins applied to.

For additional information, please refer to the Endpoints section.

plugins
array
optional

List of global plugins to be applied to all endpoints. Global plugins are applied before endpoint-specific plugins.