Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Edits on Apollo Server metrics article #3180

Merged
merged 2 commits into from
Aug 21, 2019
Merged

Edits on Apollo Server metrics article #3180

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8abc1d6
Edit on Apollo Server metrics
Aug 20, 2019
479bbff
Tweak a heading
Aug 21, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 30 additions & 30 deletions docs/source/features/metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
---
title: Monitoring and metrics
title: Metrics and logging
description: How to monitor Apollo Server's performance
---

Understanding GraphQL execution inside of Apollo Server is critical to developing and running a production GraphQL layer. Apollo Server provides sophisticated GraphQL monitoring via integration with Apollo Graph Manager, along with native mechanisms for logging each phase of a GraphQL request.
Apollo Server integrates seamlessly with Apollo Graph Manager to help you monitor the execution of your GraphQL operations. It also provides configurable mechanisms for logging each phase of a GraphQL operation.

> Using Federation? Check out the documentation for [federated tracing](/federation/metrics/)
> Using Federation? Check out the documentation for [federated tracing](/federation/metrics/).

## Apollo Graph Manager
## Sending metrics to Apollo Graph Manager

[Apollo Graph Manager](https://www.apollographql.com/docs/platform/graph-manager-overview/) provides an integrated hub for all of your GraphQL performance data. Obtain an API key from the [Graph Manager UI](https://engine.apollographql.com/) and provide it to Apollo Server to enable automatic reporting of performance and error data. Graph Manager aggregates and displays information for your [schema](https://www.apollographql.com/docs/engine/features/performance.html), [queries](https://www.apollographql.com/docs/engine/features/query-tracking.html), [requests](https://www.apollographql.com/docs/engine/performance.html), and [errors](https://www.apollographql.com/docs/engine/features/error-tracking.html). You can also configure [alerts](https://www.apollographql.com/docs/engine/features/alerts.html) that support [Slack](https://www.apollographql.com/docs/engine/integrations/slack.html) and [Datadog](https://www.apollographql.com/docs/engine/integrations/datadog.html) integrations.
[Apollo Graph Manager](https://www.apollographql.com/docs/platform/graph-manager-overview/) provides an integrated hub for all of your GraphQL performance data. It aggregates and displays information for your [schema](https://www.apollographql.com/docs/engine/features/performance.html), [queries](https://www.apollographql.com/docs/engine/features/query-tracking.html), [requests](https://www.apollographql.com/docs/engine/performance.html), and [errors](https://www.apollographql.com/docs/engine/features/error-tracking.html). You can also configure [alerts](https://www.apollographql.com/docs/engine/features/alerts.html) that support [Slack](https://www.apollographql.com/docs/engine/integrations/slack.html) and [Datadog](https://www.apollographql.com/docs/engine/integrations/datadog.html) integrations.

To connect Apollo Server to Graph Manager, first [visit the Graph Manager UI](https://engine.apollographql.com/) to get a Graph Manager API key.
### Connecting to Graph Manager

You can provide the API key to Apollo Server in any of the following ways:
To connect Apollo Server to Graph Manager, first [visit the Graph Manager UI](https://engine.apollographql.com/) to get a Graph Manager API key. You can provide this API key to Apollo Server in one of the following ways:

* Include the API key in the constructor options for `ApolloServer`
* Assign the API key to the `ENGINE_API_KEY` environment variable
* Include the API key in the constructor options for `ApolloServer`.
* Assign the API key to the `ENGINE_API_KEY` environment variable.

### Providing an API key via the `ApolloServer` constructor

Expand Down Expand Up @@ -50,39 +50,40 @@ server.listen().then(({ url }) => {
You can provide your Graph Manager API key to Apollo Server via the `ENGINE_API_KEY` environment variable. Similarly, you can assign a particular [variant](https://www.apollographql.com/docs/platform/schema-registry/#managing-environments)
to an Apollo Server instance via the `ENGINE_SCHEMA_TAG` environment variable.

You can set environment variable values on the command line as seen below, or by using the [`dotenv` npm package](https://www.npmjs.com/package/dotenv) (or similar).
You can set environment variable values on the command line as seen below, or with the [`dotenv` npm package](https://www.npmjs.com/package/dotenv) (or similar).

```bash
# Replace the example values below with values specific to your use case.
ENGINE_API_KEY=YOUR_API_KEY ENGINE_SCHEMA_TAG=development node start-server.js
```

### Client awareness
### Identifying distinct client versions
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For my own curiosity and understanding: Is the idea here to change the title to describe the user action rather than the feature?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct. This isn't an across-the-board change that we need to make or anything, but since "client awareness" isn't a universally known term, it felt appropriate to err on the side of the task instead of the feature in this case.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since there's a specific configuration notion of client version below, my initial thought was that the inclusion of versions in this title was possibly too specific.

In other words, if Identifying distinct clients would be better.

Anyhow, definitely not asking for a change on this, just noting my instinct.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good call! Will change.


> For additional information on client awareness, please see the section in our Apollo Platform documentation on [client awareness](https://www.apollographql.com/docs/platform/client-awareness).
Graph Manager's [client awareness feature](https://www.apollographql.com/docs/platform/client-awareness) enables you to view metrics for distinct versions
of your clients. To enable this, your clients need to include some or all of the following identifying information in the headers of GraphQL requests they
send to Apollo Server:

Setting up client awareness enables client-based filtering of metrics and usage patterns within Apollo Graph Manager. A client's identity has three configurable dimensions:
| Identifier | Header Name (default) | Example Value |
|----|----|----|
| Client name | `apollographql-client-name` | `iOS Native` |
| Client version | `apollographql-client-version` | `1.0.1` |

* Name (e.g. "Android App")
* Version (e.g. `1.0.1`)
* Reference ID (e.g. A Git reference or other supporting identifier)
Each of these fields can have any string value that's useful for your application.
To simplify the browsing and sorting of your client data in Graph Manager,
a three-part version number (such as `1.0.1`) is recommended for client versions.

There are two ways to configure client awareness:
> Client version is **not** tied to your current version of Apollo
> Client (or any other client library). You define this value and are responsible
> for updating it whenever meaningful changes are made to your client.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a great distinction to make!


1. By setting specific headers on the client which are automatically picked up by Apollo Server.
2. Defining a custom `generateClientInfo` implementation within Apollo Server, allowing the use of different headers or other information from the request context.
#### Setting client awareness headers in Apollo Client

#### Default client identification headers
If you're using Apollo Client, you can set default values for client name and
version in the [`ApolloClient` constructor](https://www.apollographql.com/docs/react/api/apollo-client/#the-apolloclient-constructor). All requests to Apollo Server will automatically include these values in the appropriate headers.

By default, Apollo Server automatically recognizes the following headers on incoming requests and associates them with a client's identity on a trace automatically:
#### Using custom headers

* `apollographql-client-name`
* `apollographql-client-version`
* `apollographql-client-reference-id`

#### Custom client identification

For more advanced cases, or to use custom headers, pass a `generateClientInfo` function into the `ApolloServer` constructor:
For more advanced cases, or to use headers other than the default headers, pass a `generateClientInfo` function into the `ApolloServer` constructor:

```js{9-24}
const { ApolloServer } = require("apollo-server");
Expand Down Expand Up @@ -118,8 +119,7 @@ server.listen().then(({ url }) => {
});
```

> Note: the default implementation looks at `clientInfo` field in the
> `extensions` of the GraphQL request
Specifying this function overrides the [`defaultGenerateClientInfo` function](https://github.com/apollographql/apollo-server/blob/master/packages/apollo-engine-reporting/src/extension.ts#L205-L228) that Apollo Server calls otherwise.

## Logging

Expand Down