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 that support instrumentation:
Router service - Operates within the context of an HTTP server, handling the opaque bytes of an incoming HTTP request. Does query analysis to parse the GraphQL operation and validate it against schema.
Supergraph service - Handles a GraphQL request after it's been parsed and validated, and before it's sent to subgraphs. Runs the query planner to produce a query plan to execute.
Subgraph service - Handles GraphQL subgraph requests that have been executed as part of a query plan. Creates HTTP client requests to subgraphs.
The router, supergraph and subgraph sections are used to define custom event configuration for each service:
1telemetry:
2 instrumentation:
3 events:
4 router:
5 # ...
6 supergraph:
7 # ...
8 subgraph:
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.
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:
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:
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
For each service you can also configure custom events.
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- 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|responsethat produce output for all router lifecycle services should only be used for development or debugging, not for production.
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.
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.
1telemetry:
2 instrumentation:
3 events:
4 router:
5 acme.event:
6 on: request # request, response, event_response, error
7 # ...
event_responseis useful when you want to directly access to the json response body. It also works for subscription events and@deferchunks.
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:
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:
1telemetry:
2 instrumentation:
3 events:
4 router:
5 acme.event:
6 # ...
7 condition:
8 eq:
9 - 200
10 - response_status: CodeFor 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.
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 reference
You can configure events with the following options:
| Option | Values | Default | Description |
|---|---|---|---|
<attribute-name> | The name of the custom attribute. | ||
attributes | standard attributes or selectors | The attributes of the custom log event. | |
condition | conditions | The condition that must be met for the event to be emitted. | |
error | trace|info|warn|error| off | off | The level of the error log event. |
level | trace|info|warn|error| off | off | The level of the custom log event. |
message | The message of the custom log event. | ||
on | request|response|error | When to trigger the event. | |
request | trace|info|warn|error| off | off | The level of the request log event. |
response | trace|info|warn|error| off | off | The level of the response log event. |
Event configuration examples
Standard and custom events
You can use both standard events and custom events in the same configuration. The example below has all the standard events (request, response, error) and one custom event (my.event) with a condition:
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 ...Debugging subscriptions
When developing and debugging the router, you might want to log all subscription events. The example configuration below logs all subscription events for both errors and data.
1telemetry:
2 instrumentation:
3 events:
4 supergraph:
5 subscription.event:
6 message: subscription event
7 on: event_response # on every subscription event
8 level: info
9 # Only display event if it's a subscription event
10 condition:
11 eq:
12 - operation_kind: string
13 - subscription
14 attributes:
15 response.data:
16 response_data: $ # Display all the response data payload
17 response.errors:
18 response_errors: $ # Display all the response errors payload