Sending operation metrics to GraphOS

From the Apollo Router or Apollo Server

Both the Apollo Router and Apollo Server use the same mechanism to enable operation metrics reporting to GraphOS:

1. Obtain a graph API key from Studio.

   How to obtain a graph API key

   API keys are secret credentials. Never share them outside your organization or commit them to version control. Delete and replace API keys that you believe are compromised.

   1. Go to studio.apollographql.com and click the graph you want to obtain an API key for.

   2. If a "Publish your Schema" dialog appears, copy the protected value that appears after APOLLO_KEY= in the example code block (it begins with service:), and you're all set.

      Otherwise, proceed to the next step.

   3. Open your graph's Settings page and select the API Keys tab. Click Create New Key. Give your key a name, such as Production. This helps you keep track of each API key's use.

      If you don't see the API Keys tab, you don't have sufficient permissions for your graph. Only organization members with the Org Admin or Graph Admin role can manage graph API keys. Learn more about member roles.

   4. Copy the key's value. For security, you cannot view an API key's value in Studio after creating it.

2. Obtain the graph ref for the graph and variant you want to report metrics for.

   Your variant's graph ref is shown at the top of its README page in Apollo Studio. It has the format graph-id@variant-name (such as my-graph@staging).

3. Use the obtained values to set the following environment variables in your environment before starting up your router/server:

   Bash

   1
   export APOLLO_KEY=<YOUR_GRAPH_API_KEY>
   2
   export APOLLO_GRAPH_REF=<YOUR_GRAPH_REF>

   Copy

Now when your router/server starts up, it automatically begins reporting operation metrics to GraphOS.

Adding support to a third-party server (advanced)

You can set up a reporting agent in your GraphQL server to push metrics to Apollo Studio. The agent is responsible for:

• Translating operation details into the correct trace format
• Implementing a default signature function to identify each executed operation
• Emitting batches of traces to the Apollo Studio reporting endpoint
• Optionally defining plugins to enable advanced reporting features

Apollo Server defines its agent for performing these tasks in the usage reporting plugin.

Tracing format

Apollo Studio's reporting endpoint accepts batches of traces that are encoded in protocol buffer format. Each trace corresponds to the execution of a single GraphQL operation, including a breakdown of the timing and error information for each field that's resolved as part of the operation.

The schema for this protocol buffer is defined as the Report message in the TypeScript reference implementation.

As a starting point, we recommend implementing an extension to the GraphQL execution that creates a report with a single trace, as defined in the Trace message of the protobuf schema. Then, you can batch multiple traces into a single report. We recommend sending batches approximately every 20 seconds, and limiting each batch to a reasonable size (~4MB).

An example of a FullTracesReport message, represented as JSON, is provided below.

Operation signing

For Apollo Studio to correctly group GraphQL queries, your reporting agent should define a function to generate a query signature for each distinct query. This can be challenging, because two structurally different queries can be functionally equivalent. For instance, all of the following queries request the same information:

1
query AuthorForPost($foo: String!) {
2
  post(id: $foo) {
3
    author
4
  }
5
}
6

7
query AuthorForPost($bar: String!) {
8
  post(id: $bar) {
9
    author
10
  }
11
}
12

13
query AuthorForPost {
14
  post(id: "my-post-id") {
15
    author
16
  }
17
}
18

19
query AuthorForPost {
20
  post(id: "my-post-id") {
21
    writer: author
22
  }
23
}

It's important to decide how to group such queries when tracking metrics. The TypeScript reference implementation does the following to every query before generating its signature to better group functionally equivalent operations:

• Drop unused fragments and/or operations
• Hide string literals
• Ignore aliases
• Sort the tree deterministically
• Ignore differences in whitespace.

We recommend using the same default signature method for consistency across different server runtimes.

Sending metrics to the reporting endpoint

After your GraphQL server prepares a batch of traces, it should send them to the Studio reporting endpoint at the following URL:

1
https://usage-reporting.api.apollographql.com/api/ingress/traces

Each batch should be sent as an HTTP POST request. The body of the request can be one of the following:

• A binary serialization of a FullTracesReport message
• A gzipped binary serialization of a FullTracesReport message

To authenticate with Studio, each request must include either:

• An X-Api-Key header with a valid API key for your graph
• An authtoken cookie with a valid API key for your graph

Only graph-level API keys (starting with the prefix service:) are supported.

The request can also optionally include a Content-Type header with value application/protobuf, but this is not required.

For a reference implementation, see the sendReport() function in the TypeScript reference agent.

Tuning reporting behavior

We recommend implementing retries with backoff when you encounter 5xx responses or networking errors when communicating with the reporting endpoint. Additionally, implement a shutdown hook to make sure you push all pending reports before your server initiates a healthy shutdown.

Implementing additional reporting features

The reference TypeScript implementation includes several features that you might want to include in your implementation. All of these features are implemented in the usage reporting plugin itself, and are documented the plugin's API reference.

For example, you can restrict which information is sent to Studio, particularly to avoid reporting personal data. Because personal data most commonly appears in variables and headers, the TypeScript agent offers options to sendVariablesValues and sendHeaders.

Example FullTracesReport message

The FullTracesReport message must be provided to the Studio reporting endpoint in protocol buffer format, as described in Tracing format. This example is shown in JSON format to illustrate the structure of the message.

1
{
2
  "header": {
3
    "hostname": "www.example.com",
4
    "schemaTag": "staging",
5
    "schemaHash": "alskncka384u1923e8uino1289jncvo019n"
6
  },
7
  "tracesPerQuery": {
8
    "# Foo\nquery Foo { user { email pets { name } } }": {
9
      "trace": [
10
        {
11
          "endTime": "2018-11-25T18:28:36.604Z",
12
          "startTime": "2018-11-25T18:28:36.104Z",
13
          "clientName": "c1",
14
          "clientVersion": "v1",
15
          "http": {
16
            "method": "POST"
17
          },
18
          "durationNs": "2498055950907169",
19
          "root": {
20
            "child": [
21
              {
22
                "response_name": "user",
23
                "type": "User",
24
                "start_time": "16450765",
25
                "end_time": "750079190",
26
                "child": [
27
                  {
28
                    "response_name": "email",
29
                    "type": "String",
30
                    "start_time": "750122948",
31
                    "end_time": "750145101",
32
                    "parent_type": "User"
33
                  }
34
                ],
35
                "parent_type": "Query"
36
              }
37
            ]
38
          }
39
        },
40
        {
41
          "endTime": "2018-11-25T18:28:37.004Z",
42
          "startTime": "2018-11-25T18:28:36.404Z",
43
          "clientName": "c2",
44
          "clientVersion": "v1",
45
          "http": {
46
            "method": "POST"
47
          },
48
          "durationNs": "13154220",
49
          "clientReferenceId": "c2_id",
50
          "root": {
51
            "child": [
52
              {
53
                "response_name": "user",
54
                "type": "User",
55
                "start_time": "16450962",
56
                "end_time": "750079190",
57
                "child": [
58
                  {
59
                    "response_name": "email",
60
                    "type": "String",
61
                    "start_time": "720132958",
62
                    "end_time": "720145167",
63
                    "parent_type": "User"
64
                  },
65
                  {
66
                    "response_name": "pets",
67
                    "type": "[Pet]",
68
                    "start_time": "720132959",
69
                    "end_time": "720135177",
70
                    "parent_type": "User",
71
                    "child": [
72
                      {
73
                        "index": 0,
74
                        "child": [
75
                          {
76
                            "response_name": "name",
77
                            "type": "String",
78
                            "start_time": "720133006",
79
                            "end_time": "720133039",
80
                            "parent_type": "Pet"
81
                          }
82
                        ]
83
                      },
84
                      {
85
                        "index": 1,
86
                        "child": [
87
                          {
88
                            "response_name": "name",
89
                            "type": "String",
90
                            "start_time": "720133041",
91
                            "end_time": "720133102",
92
                            "parent_type": "Pet"
93
                          }
94
                        ]
95
                      }
96
                    ]
97
                  }
98
                ],
99
                "parent_type": "Query"
100
              }
101
            ]
102
          }
103
        }
104
      ]
105
    }
106
  }
107
}