This repository has been archived by the owner on Sep 20, 2019. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Organize and fix docs and defaults (#18)
* tracer package * configure package and webpack for distribution * separate logEntry and formatEntry; send entry to elastic * shallow copy elastic.Client options because elastic/elasticsearch-js#33 * add API docs to readme * adjust readme * Update README.md * configure frontend to work with trace data in elasticsearch * add circleci config * Update README.md * move elastic call to componentDidMount * move jest.json to root and only call test once in circle * remove fast-async * run packages/tracer/yarn install in circle * try different syntax for circle deps * Add basic functional analytics frontend * Remove superfluous curly braces from App.js * Swap metrics and query columns * Organize and add documentation * Fix README anchoring/linking * Fix README linking * Use instead of as default index name
- Loading branch information
Showing
3 changed files
with
126 additions
and
90 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,104 +1,30 @@ | ||
| # GraphQL Optics [](https://circleci.com/gh/kiwicom/graphql-optics) | ||
| # graphql-optics | ||
|
|
||
| Tracing library and analyitcs dashboard for GraphQL. Engineered as an extensible replacement for ApolloEnging. | ||
|
|
||
| ## Usage with `graphql-express` and `apollo-tracing` | ||
|
|
||
| Install the package | ||
|
|
||
| ``` | ||
| yarn add graphql-optics-tracer | ||
| ``` | ||
|
|
||
| In the module where you instantiate and assign the graphqlHTTP middleware: | ||
|
|
||
| ```javascript | ||
| import { formatEntry, logEntry } from 'graphql-optics-tracer' | ||
| import schema from './yourGraphQLSchema' | ||
| import { | ||
| TraceCollector, | ||
| instrumentSchemaForTracing, | ||
| formatTraceData, | ||
| } from 'apollo-tracing' | ||
|
|
||
| app.use('/', (request, response) => { | ||
| // start the timer | ||
| const traceCollector = new TraceCollector() | ||
| traceCollector.requestDidStart() | ||
|
|
||
| graphqlHTTP((req, res, params) => ({ | ||
| schema: instrumentSchemaForTracing(schema), | ||
| extensions: req => { | ||
| traceCollector.requestDidEnd() | ||
| const definitions = req.document.definitions | ||
| const graphql = graphQLParams.query | ||
| const metrics = formatTraceData(traceCollector) | ||
| const entry = formatEntry({ request: { definitions, graphql }, metrics }) | ||
| logEntry({ entry }) | ||
| return {} | ||
| }, | ||
| }))(request, response) | ||
| }) | ||
| ``` | ||
| [](https://circleci.com/gh/kiwicom/graphql-optics) | ||
|
|
||
| ## API | ||
|
|
||
| #### formatEntry({ request, metrics }) | ||
|
|
||
| Formats a graphQL query for logging. | ||
|
|
||
| _request_ | ||
| Tracing library and analyitcs dashboard for GraphQL. Engineered as an extensible replacement for ApolloEnging. | ||
|
|
||
| ``` | ||
| { | ||
| definitions, // from express-graphql | ||
| graphql // raw graphQL query as string | ||
| } | ||
| ``` | ||
| ## Getting started | ||
|
|
||
| _metrics_ | ||
| Object in apollo-tracing format. | ||
| Ex: return value of apolloTracing.formatTraceData. | ||
| #### Elasticsearch | ||
|
|
||
| Returns an object to be passed to logEntry | ||
| If you don't have an elasticsearch instance you can use for staging, try the [zero-configuration Docker image](https://www.docker.elastic.co/). The default settings there match the default configuration in the dashboard app and tracer package. | ||
|
|
||
| #### logEntry({ entry, options }) | ||
| #### Tracing data | ||
|
|
||
| Sends entry data to ElasticSearch for indexing | ||
| Follow the installation and usage instructions in the [graphql-optics-tracing](packages/tracer) package. Then send some requests to your graphql server, perhaps using the [graphiql IDE](https://github.com/graphql/graphiql). | ||
|
|
||
| _entry_ (required) | ||
| Return value of formatEntry | ||
| ## Launching the dashboard | ||
|
|
||
| _options_ | ||
| ElasticSearch options. | ||
| Configure your app in `src/config.json`. If you're using [graphql-optics-tracing](packages/tracer), these should match the options you pass to [logEntry](packages/tracer#logentry). | ||
|
|
||
| Defaults: | ||
| Install dependencies and launch the app. | ||
|
|
||
| ``` | ||
| { | ||
| elasticIndex: 'graphql', | ||
| elasticClient: { | ||
| host: 'localhost:9200', | ||
| log: 'trace', | ||
| }, | ||
| } | ||
| yarn install | ||
| yarn dev | ||
| ``` | ||
|
|
||
| ## Configuring elastic mappings | ||
|
|
||
| Before constructing the aggregations, you will need to run the following against your elasticsearch instance. Replace `graphql_test` with the name of the index you will use in your app. | ||
| ## Packages | ||
|
|
||
| ``` | ||
| PUT graphql_test | ||
| {} | ||
| PUT graphql_test/_mapping/graphql | ||
| { | ||
| "properties": { | ||
| "rootQuery": { | ||
| "type": "keyword", | ||
| "index": true | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| [graphql-optics-tracing](packages/tracer) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| # graphql-optics-tracer | ||
|
|
||
| [](https://circleci.com/gh/kiwicom/graphql-optics) | ||
|
|
||
| Tracing library for GraphQL. Designed to work with graphql-express and apollo-tracing, but generic enough to use with other graphql servers and tracing packages. | ||
|
|
||
| ## Usage with `graphql-express` and `apollo-tracing` | ||
|
|
||
| Install the package | ||
|
|
||
| ``` | ||
| yarn add graphql-optics-tracer | ||
| ``` | ||
|
|
||
| In the module where you instantiate and assign the graphqlHTTP middleware: | ||
|
|
||
| ```javascript | ||
| import { formatEntry, logEntry } from 'graphql-optics-tracer' | ||
| import schema from './yourGraphQLSchema' | ||
| import { | ||
| TraceCollector, | ||
| instrumentSchemaForTracing, | ||
| formatTraceData, | ||
| } from 'apollo-tracing' | ||
|
|
||
| app.use('/', (request, response) => { | ||
| // start the timer | ||
| const traceCollector = new TraceCollector() | ||
| traceCollector.requestDidStart() | ||
|
|
||
| graphqlHTTP((req, res, params) => ({ | ||
| schema: instrumentSchemaForTracing(schema), | ||
| extensions: req => { | ||
| traceCollector.requestDidEnd() | ||
| const definitions = req.document.definitions | ||
| const graphql = graphQLParams.query | ||
| const metrics = formatTraceData(traceCollector) | ||
| const entry = formatEntry({ request: { definitions, graphql }, metrics }) | ||
| logEntry({ entry }) | ||
| return {} | ||
| }, | ||
| }))(request, response) | ||
| }) | ||
| ``` | ||
|
|
||
| ## API | ||
|
|
||
| #### formatEntry | ||
|
|
||
| Formats a graphQL query for logging. | ||
|
|
||
| ##### Arguments: ({ request, metrics }) | ||
|
|
||
| _request_ | ||
|
|
||
| ``` | ||
| { | ||
| definitions, // from express-graphql | ||
| graphql // raw graphQL query as string | ||
| } | ||
| ``` | ||
|
|
||
| _metrics_ | ||
| Object in apollo-tracing format. | ||
| Ex: return value of apolloTracing.formatTraceData. | ||
|
|
||
| Returns an object to be passed to logEntry | ||
|
|
||
| #### logEntry | ||
|
|
||
| Sends entry data to ElasticSearch for indexing | ||
|
|
||
| ##### Arguments: ({ entry, options }) | ||
|
|
||
| _entry_ (required) | ||
| Return value of formatEntry | ||
|
|
||
| _options_ | ||
| ElasticSearch options. | ||
|
|
||
| Defaults: | ||
|
|
||
| ``` | ||
| { | ||
| elasticIndex: 'graphql', | ||
| elasticClient: { | ||
| host: 'localhost:9200', | ||
| log: 'trace', | ||
| }, | ||
| } | ||
| ``` | ||
|
|
||
| ## Configuring elastic mappings | ||
|
|
||
| Before constructing the aggregations, you will need to run the following against your elasticsearch instance. If necessary, replace `graphql` with the name of the index you will use in your app. | ||
|
|
||
| ``` | ||
| PUT graphql | ||
| {} | ||
| PUT graphql/_mapping/graphql | ||
| { | ||
| "properties": { | ||
| "rootQuery": { | ||
| "type": "keyword", | ||
| "index": true | ||
| } | ||
| } | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters