Logging in the Apollo Router

The Apollo Router accepts a command-line argument to set its log level:

Name	Description
`--log`	The log level, indicating the most severe log message type to include. In ascending order of verbosity, can be one of: `off`, `error`, `warn`, `info`, `debug`, or `trace`. The default value is `info`.

The router also accepts both RUST_LOG and APOLLO_ROUTER_LOG environment variables with the same possible values as the command-line argument. The precedence is as follows (top to bottom):

RUST_LOG
command-line argument
APOLLO_ROUTER_LOG

RUST_LOG is supported for advanced users with specific filtering requirements who may wish to see log messages from crates consumed by the router. Most users should use the command-line argument or APOLLO_ROUTER_LOG. Both of these options constrain log output to the router.

To be clear:

1
RUST_LOG=apollo_router::debug
2
APOLLO_ROUTER_LOG=debug
3
--log=debug

are equivalent, as are:

1
RUST_LOG=hyper=debug,apollo_router::info,h2=trace
2
APOLLO_ROUTER_LOG=hyper=debug,info,h2=trace
3
--log=hyper=debug,info,h2=trace

In both examples, the actual filter used by the router is as defined in the RUST_LOG entry.

For more information about specifying filters for more granular control over Apollo Router logging, see the Env Logger documentation.

Output formats

The Apollo Router supports two logging formats:

Basic logging, primarily for local development
JSON-formatted logging, for compatibility with searchable logging tools like Google Cloud Logging

The router uses basic logging whenever an interactive shell session is attached, and it uses JSON-formatted logging otherwise (e.g., in CI and deployed environments). You can also enforce a specific format in configuration.

Basic logging via shell

Basic logging is mostly used during local development:

1
2022-03-18T10:28:11.090054Z  INFO apollo_router::executable: apollo-router@0.1.0-alpha.9
2
2022-03-18T10:28:11.160650Z  INFO apollo_router: Starting Apollo Router
3
2022-03-18T10:28:11.339906Z  INFO apollo_router: Listening on http://127.0.0.1:4000 🚀

JSON-formatted logging

JSON-formatted logging provides compatibility with common searchable logging tools like Google Cloud Logging. The Apollo Router uses the popular Bunyan format:

1
{"timestamp":"2022-03-18T11:46:41.926942Z","level":"INFO","fields":{"message":"apollo-router@0.1.0-alpha.9"},"target":"apollo_router::executable"}
2
{"timestamp":"2022-03-18T11:46:41.985121Z","level":"INFO","fields":{"message":"Starting Apollo Router"},"target":"apollo_router"}
3
{"timestamp":"2022-03-18T11:46:42.171173Z","level":"INFO","fields":{"message":"Listening on http://127.0.0.1:4000 🚀"},"target":"apollo_router"}
4
{"timestamp":"2022-03-18T11:46:43.453993Z","level":"INFO","fields":{"message":"Stopped"},"target":"apollo_router"}

Basic configuration

This is part of an experimental feature, it means any time until it's stabilized (without the prefix experimental_) we might change the configuration shape or adding/removing features. If you want to give feedback or participate in that feature feel free to join this discussion on GitHub.

By default, the router doesn't log certain values that might contain sensitive data, even if a sufficient log level is set:

Request bodies
Response bodies
Headers

You can enable selective logging of these values via the when_header option:

router.yaml

1
telemetry:
2
  experimental_logging:
3
    format: json # By default it's "pretty" if you are in an interactive shell session
4
    display_filename: true # Display filename where the log is coming from. Default: true
5
    display_line_number: false # Display line number in the file where the log is coming from. Default: true
6
    # If one of these headers matches we will log supergraph and subgraphs requests/responses
7
    when_header:
8
      - name: apollo-router-log-request
9
        value: my_client
10
        headers: true # default: false
11
        body: true # default: false
12
      # log request for all requests coming from Iphones
13
      - name: user-agent
14
        match: ^Mozilla/5.0 (iPhone*
15
        headers: true

Distributed caching

Subgraph error inclusion