Engine runs as a proxy layer in front of GraphQL, provides performance telemetry (Optics functionality) and caches whole responses.
Engine currently supports the following GraphQL Servers:
- Apollo Server - Express, Hapi, Koa, Restify and Lambda
- Express-GraphQL
- GraphQL-Ruby
- GraphQL-Java
- Sangria
- Elixir
The Engine Proxy can be deployed through either of two deployment options: Side-loader package or Standalone Docker container.
Available for: Node servers
This is a language-specific package that you add to your server - for Node, it replaces the https://github.com/apollographql/optics-agent-js agent. This package includes a pre-built copy of the Engine proxy. It spawns an Engine process side-by-side with the Graphql server process. Incoming graphql operations get routed through the proxy and then into your server.
Choose the side-loader package in environments where you don't want to orchestrate and manage the proxy process separately.
Available for: Node, Java, Scala and Elixir servers
This is a Docker container that contains the Engine proxy process. Use this to deploy and manage the Proxy as a separate process.
Choose the standalone configuration in environments where you want to control the orchestration and management directly. You'll need to use the standalone configuration for GraphQL server on Lambda support.
These are the set of steps you'll follow to configure Engine:
- Install the Engine proxy. Choose to deploy and configure either the side-loader package or the standalone Docker container.
- Install Apollo tracing for your GraphQL server
- Get an API key (from engine.apollographql.com (http://engine.apollographql.com/)) and add to your Engine Proxy configuration
- Deploy your server - you are then all set up!
The Proxy uses a JSON object to get configuration information. If the configuration is provided as a filename, that file will be watched for changes. Changes will cause the proxy to adopt the new configuration without downtime.
Here's the minimal sideloader engine configuration JSON:
{
"apiKey": "<ENGINE_API_KEY>"
}
Install the npm package:
npm install --save https://s3.us-east-2.amazonaws.com/apollo-engine-deploy/apollo-engine-0.3.0.tgz
Usage:
import { Engine } from 'apollo-engine';
// create new engine instance from JS config object
const engine = new Engine({ engineConfig: { ... } });
// create new engine instance from file
const engine = new Engine({ engineConfig: 'path/to/config.json' });
await engine.start();
// Invoke the function that corresponds to your Node Middleware. Choose from expressMiddleware(), connectMiddleware(), instrumentHapiServer() or koaMiddleware()
// For example, when using Express:
app.use(engine.expressMiddleware());
// ...
// other middleware / handlers
// ...
These are optional configurations for engine sideloader:
{
engineConfig: string | EngineConfig, // Engine Configuration filename or object
endpoint?: string, // GraphQL endpoint - '/graphql' by default
graphqlPort?: number // GraphQL port - 'process.env.PORT' by default
}
The graphql server should have tracing enabled if available. If you are using Apollo Server (v1.1.0 or newer), enable the tracing: true configuration option.
In case you need to control killing the Engine process, you can use the following code:
engine.stop();
The available log levels are “debug”, “info” (default), “warn”, “error”, and “fatal”.
The proxy is also available as a Docker image that can be deployed as a standalone process. Configuration of a standalone proxy is the same as that of the sideloader, with the addition of the 'frontends' and 'origins' fields:
{
"origins": [
{
"url": "http://localhost:3000/graphql"
}
],
"frontends": [
{
"host": "127.0.0.1",
"port": 3001,
"endpoint": "/graphql"
}
],
"apiKey": "<ENGINE_API_KEY>",
"logcfg": {
"level": "INFO"
}
}
- origin.URL : The URL for your GraphQL server
- frontend.host : The hostname the proxy should be available on
- frontend.port : The port the proxy should bind to
- frontend.endpoint : The path for the GraphQL server . This is usually /graphql.
To configure a Lambda origin, use the following configuration for the origin:
{
"url":"arn:aws:lambda:xxxxxxxxxxx:xxxxxxxxxxxx:function:xxxxxxxxxxxxxxxxxxx",
"id":"xxxxxxxxxxxxxxxxxxxx",
"secret":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"originType": "Lambda"
}
To run the proxy:
engine_config_path=/path/to/engine.json
proxy_frontend_port=3001
docker run --env "ENGINE_CONFIG=$(cat "${engine_config_path}")" \
-p "${proxy_frontend_port}:${proxy_frontend_port}" \
gcr.io/mdg-public/engine-ea-confidential:2017.08-19-g8eb44893
Install Apollo tracing in your GraphQL server to enable Engine to receive performance traces for your GraphQL requests.
Here's the instructions for each GraphQL server:
- For Node: https://github.com/apollographql/apollo-tracing-js
- For Ruby: https://github.com/uniiverse/graphql-tracing
- For Scala: https://gist.github.com/OlegIlyenko/124b55e58609ad45fcec276f15158d16
- For Java: graphql-java/graphql-java#577
- For Elixir: https://github.com/sikanhe/apollo-tracing-elixir
For other servers, find instructions here: https://github.com/apollographql/apollo-tracing#supported-graphql-servers
We recommend that people enable gzip compression in their GraphQL server, because the tracing format adds to the response size but compresses well.
Express
Install the compression middleware (https://github.com/expressjs/compression) package into your app with npm install compression --save and add it to your server's middleware stack:
var compression = require('compression')
app.use(compression());
Koa
Install the compress middleware (https://github.com/koajs/compress) package into your app with npm install koa-compress --save and add it to your server's middleware stack:
var compress = require('koa-compress')
app.use(compress())
Hapi
Hapi comes with support for compression enabled by default, unless it has been configured with compression: false.
Once your server is set up, navigate to the endpoint in your Engine account - https://engine.apollographql.com (https://engine.apollographql.com/)/. You'll then be able to see performance metrics!
Engine allows you to cache whole GraphQL query responses. You can use Memcached as the cache store. You can set TTLs per query signature.
These are the the steps to configure whole query caching:
- Configure cache stores
- Configure caching policies for operation signatures
- Add the caching configuration to the Engine config JSON
Engine supports one or more cache stores. Each cache store can consist of one or more Memcached instances or in-process caches.
Here's an example configuration entry for cache stores:
"stores": [
{
"name": "standardCache",
"timeout": "1s",
"memcaches": [
{
"url": "localhost:11211"
}
]
}
],
where:
- name: user given id for the cache store
- timeout: the timeout for the Proxy to connect to Memcached
- memcaches: list of Memcache instances to be used for this cache store. Each Memcached configuration contains a Memcached URL. If this is omitted, an in-memory cache is created.
Here's an example configuration entry for configuring TTL and a cache store for each operation signature:
"operations": [
{
"signature": "{hero{name}}",
"caches": [
{
"ttl": 600,
"store": "standardCache"
}
]
}
],
To invalidate a cache store, bump the epoch number on the cache store configuration.
"stores": [
{
"name": "standardCache",
*** "epoch": 1,***
"timeout": "1s",
"memcaches": [
{
"url": "localhost:11211"
}
]
}
],
We discuss feedback and support issues in the private Slack channel #engine-earlyaccess on Apollo Slack. Send Rohit (rohit@apollodata.com or @rohit2b on Apollo Slack) a note with your Slack id, and he'll add you to the Slack channel.
