Join us on Nov 7 for GraphQL Summit Virtual

Events

Capture events from the router's request lifecycle

An event is used to signal when something of note happens in the GraphOS Router's request lifecycle . Events are output to both logs and traces.

You can configure events for each service in router.yaml. Events can be standard or custom, and they can be triggered by configurable conditions.

Event configuration

Router request lifecycle services

A router's request lifecycle has three major services:

  • Router service - Handles an incoming request before it is parsed. Works within a context of opaque bytes.

  • Supergraph service - Handles a request after it has been parsed and before it is sent to the subgraph. Works within a GraphQL context.

  • Subgraph service - Handles a request after it has been sent to the subgraph. Works within a GraphQL context.

The router, supergraph and subgraph sections are used to define custom event configuration for each service:

YAML
future.router.yaml
1telemetry:
2  instrumentation:
3    events:
4      router: # highlight-line
5        # ...     
6      supergraph: # highlight-line
7        # ...
8      subgraph: # highlight-line
9        # ...

Standard events

Each service has a set of standard events that can be configured:

  • request - The request has been received.

  • response - The response has been sent.

  • error - An error in the request lifecycle has occurred.

ⓘ note
The error level applies only to request lifecycle errors, not GraphQL errors.

To configure these events, set the level to trace, info, warn, error or off (default).

For example:

YAML
router.yaml
1telemetry:
2  instrumentation:
3    events:
4      router:
5        request: off
6        response: off
7        error: error
8        # ...

But you can also enable these standard events based on conditions (not supported on batched requests).

For example:

YAML
router.yaml
1telemetry:
2  instrumentation:
3    events:
4      router:
5        request:
6          level: info
7          condition: # Only log the router request if you sent `x-log-request` with the value `enabled`
8            eq:
9            - request_header: x-log-request
10            - "enabled"
11        response: off
12        error: error
13      supergraph:
14        response:
15          level: info
16          condition: # Only log the supergraph response containing graphql errors
17            eq:
18            - on_graphql_error: true
19            - true
20        error: error
21        # ...

Custom events

This feature is only available with a GraphOS Dedicated or Enterprise plan. You can test it out by signing up for a free GraphOS trial. To compare GraphOS feature support across all plan types, see the pricing page.

For each service you can also configure custom events.

YAML
future.router.yaml
1telemetry:
2  instrumentation:
3    events:
4      router:
5        # Custom events
6        my.event: # This key will automatically be added as a 'type' attribute of the event
7          # Custom event configuration
ⓘ note
Keep in mind that the amount of telemetry you add can impact your router's performance.
  • Custom metrics, events, and attributes consume more processing resources than standard metrics. Adding too many (standard or custom) can slow your router down.
  • Configurations such as events.*.request|error|response that produce output for all router lifecycle services should only be used for development or debugging, not for production.
For properly logged telemetry, you should use a log verbosity of info. Set the values of RUST_LOG or APOLLO_ROUTER_LOG environment variables and the --log CLI option to info. Using less verbose logging, such as error, can cause some attributes to be dropped.

message

Each custom event must have a message. This is a fixed value, and custom attributes should be used to add additional information.

YAML
future.router.yaml
1telemetry:
2  instrumentation:
3    events:
4      router:
5        acme.event:
6          message: "my event message"
7          # ...

on

Each custom event must indicate when it should be triggered. This can be request, response, event_response or error.

YAML
future.router.yaml
1telemetry:
2  instrumentation:
3    events:
4      router:
5        acme.event:
6          on: request # request, response, event_response, error
7          # ...

event_response is useful when you want to directly access to the json response body. It also works for subscription events and @defer chunks.

level

Custom events have a level, trace, debug, info, warn, error or off (if you want to disable this event). The level determines the severity of the event.

To set the level:

YAML
future.router.yaml
1telemetry:
2  instrumentation:
3    events:
4      router:
5        acme.event:
6          level: info # trace, debug, info, warn, error, off
7          # ...

condition

Custom events can be configured to emit under specific conditions, for example if the response status code is 200.

In router.yaml, set a condition with an equality (eq) check:

YAML
future.router.yaml
1telemetry:
2  instrumentation:
3    events:
4      router:
5        acme.event:
6          # ...
7          condition:
8            eq:
9              - 200
10              - response_status: Code

For more details, see Conditions .

attributes

Custom events may have attributes attached to them from the router's request lifecycle. These attributes are used to filter and group spans in your APM.

Attributes may be drawn from standard attributes or selectors . The attributes available depend on the service of the request lifecycle.

YAML
future.router.yaml
1telemetry:
2  instrumentation:
3    events:
4      router:
5        my.event:
6          # ...
7          attributes:
8            # Standard attributes
9            http.response.status_code: true
10            # Custom attributes
11            "my_attribute":
12              response_header: "x-my-header"

Event configuration example

For example, the router service can be configured with standard events (request, response, error), and a custom event (my.event) with a condition:

YAML
future.router.yaml
1telemetry:
2  instrumentation:
3    events:
4      router:
5        # Standard events
6        request: info
7        response: info
8        error: info
9  
10        # Custom events
11        my.event:
12          message: "my event message"
13          level: info
14          on: request
15          attributes:
16            http.response.body.size: false
17          # Only log when the x-log-request header is `log` 
18          condition:
19            eq:
20              - "log"
21              - request_header: "x-log-request"
22          
23      supergraph:
24          # Custom event configuration for supergraph service ...
25      subgraph:
26          # Custom event configuration for subgraph service ...

Event configuration reference

OptionValuesDefaultDescription
<attribute-name>The name of the custom attribute.
attributesstandard attributes or selectors The attributes of the custom log event.
conditionconditions The condition that must be met for the event to be emitted.
errortrace|info|warn|error| offoffThe level of the error log event.
leveltrace|info|warn|error| offoffThe level of the custom log event.
messageThe message of the custom log event.
onrequest|response|errorWhen to trigger the event.
requesttrace|info|warn|error| offoffThe level of the request log event.
responsetrace|info|warn|error| offoffThe level of the response log event.