Router Instruments

Standard metric instruments

GraphOS Router and Apollo Router Core provide a set of standard router instruments that expose detailed information about the router's request lifecycle. You can consume the metrics they capture by configuring a metrics exporter.

Standard router instruments are different than OpenTelemetry (OTel) instruments or custom instruments:

• Router instruments provide standard metrics about the router request lifeycle and have names starting with apollo.router or apollo_router.

• OTel instruments provide metrics about the HTTP lifecycle and have names starting with http.

• Custom instruments provide customized metrics about the router request lifecycle.

The rest of this reference lists the available standard router instruments.

GraphQL

• apollo.router.graphql_error - counts GraphQL errors in responses. Also counts errors which occur during the response validation phase, which are represented in client responses as extensions.valueCompletion instead of actual GraphQL errors. Attributes:

  • code: error code, including RESPONSE_VALIDATION_FAILED in the case of a value completion error.

Session

• apollo.router.session.count.active - Number of in-flight GraphQL requests

Cache

• apollo.router.cache.size — Number of entries in the cache

• apollo.router.cache.hit.time - Time to hit the cache in seconds

• apollo.router.cache.hit.time.count - Number of cache hits

• apollo.router.cache.miss.time - Time to miss the cache in seconds

• apollo.router.cache.miss.time.count - Number of cache misses

• apollo.router.cache.storage.estimated_size - The estimated storage size of the cache in bytes (query planner in memory only).

All cache metrics listed above have the following attributes:

• kind: the cache being queried (apq, query planner, introspection)

• storage: The backend storage of the cache (memory, redis)

Coprocessor

• apollo.router.operations.coprocessor - Total operations with coprocessors enabled.

  • coprocessor.succeeded: bool

  • coprocessor.stage: string (RouterRequest, RouterResponse, SubgraphRequest, SubgraphResponse)

• apollo.router.operations.coprocessor.duration - Time spent waiting for the coprocessor to answer, in seconds.

  • coprocessor.stage: string (RouterRequest, RouterResponse, SubgraphRequest, SubgraphResponse)

Performance

• apollo_router_schema_load_duration - Time spent loading the schema in seconds.

Query planning

• apollo.router.query_planning.warmup.duration - Time spent warming up the query planner queries in seconds.

• apollo.router.query_planning.plan.duration - Histogram of plan durations isolated to query planning time only.

• apollo.router.query_planning.total.duration - Histogram of plan durations including queue time.

• apollo.router.query_planning.plan.evaluated_plans - Histogram of the number of evaluated query plans.

Compute jobs

• apollo.router.compute_jobs.queued - A gauge of the number of jobs queued for the thread pool dedicated to CPU-heavy components like GraphQL parsing and validation, and the query planner.

• apollo.router.compute_jobs.queue_is_full - A counter of requests rejected because the queue was full.

• apollo.router.compute_jobs.duration - A histogram of time spent in the compute pipeline by the job, including the queue and query planning.

  • job.type: (QueryPlanning, QueryParsing, Introspection)

  • job.outcome: (ExecutedOk, ExecutedError, ChannelError, RejectedQueueFull, Abandoned)

• apollo.router.compute_jobs.queue.wait.duration - A histogram of time spent in the compute queue by the job.

  • job.type: (QueryPlanning, QueryParsing, Introspection)

• apollo.router.compute_jobs.execution.duration - A histogram of time spent to execute job (excludes time spent in the queue).

  • job.type: (QueryPlanning, QueryParsing, Introspection)

• apollo.router.compute_jobs.active_jobs - A gauge of the number of compute jobs being processed in parallel.

  • job.type: (QueryPlanning, QueryParsing, Introspection)

Uplink

• apollo_router_uplink_fetch_duration_seconds - Uplink request duration, attributes:

  • url: The Uplink URL that was polled

  • query: The query that the router sent to Uplink (SupergraphSdl or License)

  • kind: (new, unchanged, http_error, uplink_error)

  • code: The error code depending on type (if an error occurred)

  • error: The error message (if an error occurred)

• apollo_router_uplink_fetch_count_total

  • status: (success, failure)

  • query: The query that the router sent to Uplink (SupergraphSdl or License)

Subscriptions

• apollo.router.opened.subscriptions - Number of different opened subscriptions (not the number of clients with an opened subscriptions in case it's deduplicated). This metric contains graphql.operation.name label to know exactly which subscription is still opened.

• apollo.router.skipped.event.count - Number of subscription events that has been skipped because too many events have been received from the subgraph but not yet sent to the client.

Batching

• apollo.router.operations.batching - A counter of the number of query batches received by the router.

• apollo.router.operations.batching.size - A histogram tracking the number of queries contained within a query batch.

GraphOS Studio

• apollo.router.telemetry.studio.reports - The number of reports submitted to GraphOS Studio by the router.

  • report.type: The type of report submitted: "traces" or "metrics"

  • report.protocol: Either "apollo" or "otlp", depending on the otlp_tracing_sampler configuration.

Telemetry

• apollo.router.telemetry.batch_processor.errors - The number of errors encountered by exporter batch processors.

  • name: One of apollo-tracing, datadog-tracing, jaeger-collector, otlp-tracing, zipkin-tracing.

  • error: One of channel closed, channel full.

• apollo.router.telemetry.metrics.cardinality_overflow - A count of how often a telemetry metric hit otel's hard cardinality limit.

Internals

• apollo.router.pipelines - The number of request pipelines active in the router

  • schema.id - The Apollo Studio schema hash associated with the pipeline.

  • launch.id - The Apollo Studio launch id associated with the pipeline (optional).

  • config.hash - The hash of the configuration

Server

• apollo.router.open_connections - The number of open connections to the Router.

  • schema.id - The Apollo Studio schema hash associated with the pipeline.

  • launch.id - The Apollo Studio launch id associated with the pipeline (optional).

  • config.hash - The hash of the configuration.

  • server.address - The address that the router is listening on.

  • server.port - The port that the router is listening on if not a unix socket.

  • http.connection.state - Either active or terminating.