Where can the router send access logs?

To stdout by default (useful for Docker and Kubernetes deployments) or to a file path you configure. File output is recommended for high-load scenarios.

What fields are logged by default?

hostname, pid, request_id, trace_id, status, method, path, query, ip (redacted by default), user_agent, config_version, latency, and log_type.

What GraphQL-specific fields can I add?

operation_name, operation_type, operation_hash, operation_sha256, persisted_operation_sha256, operation_service_names, operation_parsing_time, operation_planning_time, operation_normalization_time, operation_validation_time, graphql_error_codes, graphql_error_service_names, request_error, and response_error_message.

How do I add a custom field from a header?

In the access_logs.router.fields block, define a key and a value_from entry that points to the request header. Headers, request context, and expressions are all supported. Expression fields require Cosmo Router 0.186.0 or later.

Are subgraph requests logged separately?

Yes. Subgraph access logs are emitted independently from router logs. Subgraph access logs require Cosmo Router 0.146.0 or later.

What is the default file permission?

The default file permission is 0640. The mode is configurable per file output.

Are IP addresses logged in clear?

The ip field is redacted by default. You can configure the behavior if your compliance posture requires the full address.

Access Logs for Federated GraphQL | Cosmo by WunderGraph

The problem

HTTP logs do not understand GraphQL

Method and path are not enough when one URL handles every operation. Debugging, auditing, and compliance need richer context.

Generic HTTP logs miss the operation

Standard request logs record method and path. They never know that one request was the Products query and another was the Checkout mutation.

High-traffic logging needs files

stdout works in a container; it does not work when log volume exceeds what your runtime can stream. Production needs a file output path it can rotate.

Compliance needs custom context

Security and compliance reviews ask for client identification, tenant context, and per-stage timing, fields that generic logs do not carry.

Our solution

Structured logs with the right fields

Default fields cover the request basics. Custom context fields add the GraphQL details that matter: operation, timing, errors. Custom expression and header fields attach the business context that matters to you.

Per-request logging, end to end

Access logs are emitted by the router for every request.
Default fields cover the basics: hostname, pid, request_id, trace_id, status, method, path, query, ip (redacted), user_agent, config_version, latency, and log_type.
Custom context fields add GraphQL-aware data: operation_name, operation_type, operation_hash, per-stage timing (parsing, planning, normalization, validation), error codes, and error service names.
Custom fields are populated from request headers or template expressions, so you can attach tenant IDs, client identifiers, or any business context.
Output goes to stdout for container deployments, or to a file for high-load scenarios.
Every line is structured JSON, ready for ingestion by ELK, Splunk, or any aggregator.

One config block. Every line ready for ingestion.

Access logs

Before & After

Before Cosmo	With Cosmo
HTTP access logs without GraphQL operation name	Structured JSON with operation name, duration, and status per request
High-traffic logging without a rotation-friendly sink	File output with configurable path and permissions
Compliance needs client or tenant context in every line	Custom fields from headers or router context expressions
Separate logging middleware in every subgraph	Router-level access logs for the full federated request

Custom context

GraphQL-aware fields

Operation: operation_nameoperation_typeoperation_hashoperation_sha256persisted_operation_sha256operation_service_names
Timing: operation_parsing_timeoperation_planning_timeoperation_normalization_timeoperation_validation_time
Errors: graphql_error_codesgraphql_error_service_namesrequest_errorresponse_error_message

How access logs work in Cosmo Router

01

Default fields cover the basics.

Capture

The router records access events for every request. Default fields include trace_id, status, latency, method, path, query, user_agent, and config_version.

02

GraphQL operation context per line.

Enrich

Custom context fields add GraphQL-aware data: operation_name, operation_type, operation_hash, and per-stage timing (parsing, planning, normalization, validation). Expression fields require Cosmo Router 0.186.0+.

03

stdout or file. JSON, structured.

Output

Choose stdout for container deployments or a file for high-load scenarios. File output requires Cosmo Router 0.118.0+. Subgraph access logs require 0.146.0+.

04

JSON for ELK, Splunk, SIEM, anything.

Ingest

Every line is structured JSON, ready for ELK, Splunk, a SIEM, or any log aggregator. No custom parsers required.

Telemetry controls

Output, fields, and ingestion

Stdout for containers, files for high volume, custom fields for compliance context.

Output mode

stdout for containers and Kubernetes. File output for high-load production. File access requires Cosmo Router 0.118.0+.

Custom fields

Pull values from request headers, context fields, or template expressions. Expression fields require Cosmo Router 0.186.0+.

Subgraph logs

Subgraph access logs are emitted as their own stream and can carry their own custom fields. Requires Cosmo Router 0.146.0 or later.

File permissions

File permission defaults to 0640. The mode is configurable per file output.

Enable structured access logs

Turn on access logs in router YAML. Ship JSON lines to stdout or a file your log stack already ingests.

Start Free Read the Docs

GraphQL-aware request logs in structured JSON