.svg?alt=media&token=06f1bc51-8b97-4fc6-8caf-fdd3a8cd9ec8)
Access logs
Configuring Access Logs for Enhanced Traffic Monitoring.
Available since Router 0.118.0
Access or request logs provide valuable insights into the traffic passing through your router instances. By default, logs are output to stdout, but logging to a file is also supported, which is recommended for high-load scenarios. However, only one logging mode—either stdout or file—can be enabled at any given time. The logs include a predefined set of fields that help identify HTTP requests. Additionally, custom fields can be configured to capture more detailed information from the GraphQL requests.
Logging to stdout
The following configuration enables logging to stdout:
Logging to file
For environments with high traffic, logging to a file is recommended. Below is an example configuration for logging to a file:
Default Log Fields
The default log fields provide essential details about each HTTP request. These fields include:
hostname: The hostname of the machine handling the request.
pid: The process ID of the router instance.
request_id: The request ID generated by the router instance.
trace_id: The Trace ID propagated or generated by the router instance.
status: The HTTP status code of the request.
method: The HTTP method used (e.g.,
GET,POST).path: The request path (e.g.,
/graphql).query: The query string included in the request URL (e.g.,
/?param=1).ip: The client’s IP address (redacted by default).
user_agent: The
User-Agentheader value provided by the client.config_version: The version of the router configuration used to handle the request.
latency: The time taken to process the request, in float seconds.
log_type: Identifies the type of log (useful for distinguishing access logs from other log types).
Example Log Entry
An example of a log entry is shown below:
Custom Fields
In addition to the default fields, you can extend the log with custom fields. These can include values extracted from request headers or additional information generated after the GraphQL operation has been processed.
Let's take the following example:
Here’s an explanation of each field’s meaning:
service: This field logs the name of the service making the request, extracted from the request header "x-service". It helps identify which specific service is making the API call.
operationName: This field logs the name of the GraphQL operation being performed. It is extracted from the context of the request and indicates which query or mutation is being executed.
operationSha256: This field logs the SHA-256 hash of the original GraphQL operation, serving as a unique identifier for the operation's structure. It helps to identify operations in a secure and consistent way.
responseErrorMessage: This field logs any error message returned in the response. It captures detailed information about what went wrong during the execution of the operation.
serviceNames: This field logs the names of all services involved in processing the operation. It can be useful for tracking dependencies or microservices that are part of the request's execution.
operationHash: This field logs a unique hash generated for the normalized operation. It serves as an identifier for the specific instance of the operation being executed, useful for tracing or debugging.
errorCodes: This field logs any GraphQL error codes returned in the response. These codes help diagnose issues within the GraphQL schema or logic.
operationType: This field logs the type of GraphQL operation being executed, such as a query, mutation, or subscription. It helps classify the request.
persistentOperationSha256: This field logs the SHA-256 hash of the persisted GraphQL operation. Persisted operations are pre-saved on the server for efficiency, and this hash allows tracking them.
errorServiceNames: This field logs the names of services that were involved when the operation resulted in an error. It helps identify which microservices or external APIs contributed to the issue.
operationParsingTime: This field logs the amount of time (float seconds) spent parsing the GraphQL operation. It measures how long it took to interpret the operation’s syntax.
operationPlanningTime: This field logs the time (float seconds) taken for planning the execution of the GraphQL operation, including resolving dependencies or building execution strategies.
operationNormalizationTime: This field logs the time (float seconds) spent normalizing the GraphQL operation, which involves standardizing the operation to ensure consistency in processing.
operationValidationTime: This field logs the time (float seconds) spent validating the GraphQL operation, ensuring that the operation is correct and adheres to the GraphQL schema and rules before execution.
Error-Specific Log Fields
In addition to the standard and custom fields typically present in a log, certain fields are included only in error scenarios to capture details about issues that occurred during request processing. These fields are useful for diagnosing errors in GraphQL operations and understanding the root causes.
Here are the fields that are specifically added in error cases:
graphql_error_service_names: Lists the names of the services involved in the GraphQL request where an error occurred. This helps in pinpointing which microservice(s) or backend service(s) contributed to the error.
graphql_error_codes: Provides error codes associated with the GraphQL operation. These codes may correspond to specific validation, execution, or schema-related errors that occurred during processing.
response_error_message: Contains the actual error message returned in the response. This message can be used to better understand what went wrong and why the request failed.
Default value
When extracting values from a header, it can be beneficial to ensure a default value is set. This can be achieved by defining the value as follows:
Example Log Entry
Structured log output
In development, log lines are formatted for readability using pretty printing. In production mode, all logs are output as newline-separated JSON values.
Conclusion
By configuring access logs, you can gather vital data on the traffic processed by your router. This helps in monitoring performance, debugging issues, and understanding request patterns. Whether logging to stdout or to a file, the logs provide flexibility with both default and custom fields to suit your specific needs.
Last updated