Hasura GraphQL engine logs¶

Table of contents

Accessing logs
Different log-types
Logging levels
Log structure and metrics
Monitoring frameworks

Accessing logs¶

Based on your deployment method, the Hasura GraphQL engine logs can be accessed as follows:

Different log-types¶

The Hasura GraphQL engine has different kind of log-types depending on the sub-system or the layer. A log-type is simply the type field in a log line, which indicates which sub-system the log comes from.

For example, the HTTP webserver logs incoming requests as an access log and is called http-log. Similarly logs from the websocket layer are called websocket-log, logs from the event trigger system are called event-trigger etc.

You can configure the GraphQL engine to enable/disable certain log-types using the the --enabled-log-types flag or the HASURA_GRAPHQL_ENABLED_LOG_TYPES env var. See GraphQL engine server config reference

Default enabled log-types are: startup, http-log, webhook-log, websocket-log

All the log-types that can be enabled/disabled are:

Configurable log-types¶
Log type	Description	Log Level
`startup`	Information that is logged during startup	`info`
`query-log`	Logs: the entire GraphQL query with variables, generated SQL statements (only for queries, not for mutations/subscriptions or remote schema queries), the operation name (if provided in the GraphQL request)	`info`
`http-log`	Http access and error logs at the webserver layer (handling GraphQL and metadata requests)	`info` and `error`
`websocket-log`	Websocket events and error logs at the websocket server layer (handling GraphQL requests)	`info` and `error`
`webhook-log`	Logs responses and errors from the authorization webhook (if setup)	`info` and `error`

Apart from the above, there are other internal log-types which cannot be configured:

Internal log-types¶
Log type	Description	Log Level
`pg-client`	Logs from the postgres client library	`warn`
`metadata`	Logs inconsistent metadata items	`warn`
`jwk-refresh-log`	Logs information and errors about periodic refreshing of JWK	`info` and `error`
`telemetry-log`	Logs error (if any) while sending out telemetry data	`info`
`event-trigger`	Logs HTTP responses from the webhook, HTTP exceptions and internal errors	`info` and `error`
`ws-server`	Debug logs from the websocket server, mostly used internally for debugging	`debug`
`schema-sync-thread`	Logs internal events, when it detects schema has changed on Postgres and when it reloads the schema	`info` and `error`

Logging levels¶

You can set the desired logging level on the server using the log-level flag or the HASURA_GRAPHQL_LOG_LEVEL env var. See GraphQL engine server config reference.

The default log-level is info.

Setting a log-level will print all logs of priority greater than the set level. The log-level hierarchy is: debug > info > warn > error

For example, setting --log-level=warn, will enable all warn and error level logs only. So even if you have enabled query-log it won’t be printed as the level of query-log is info.

See log-types for more details on log-level of each log-type.

Log structure and metrics¶

All requests are identified by a request id. If the client sends a x-request-id header then that is used, otherwise a request id is generated for each request. This is also sent back to the client as a response header (x-request-id). This is useful to correlate logs from the server and the client.

query-log structure¶

On enabling verbose logging, i.e. enabling query-log, GraphQL engine will log the full GraphQL query object on each request.

It will also log the generated SQL for GraphQL queries (but not mutations and subscriptions).

{
  "timestamp": "2019-06-03T13:25:10.915+0530",
  "level": "info",
  "type": "query-log",
  "detail": {
    "request_id": "840f952d-c489-4d21-a87a-cc23ad17926a",
    "query": {
      "variables": {
        "limit": 10
      },
      "operationName": "getProfile",
      "query": "query getProfile($limit: Int!) {\n  profile(limit: $limit, where: {username: {_like: \"%a%\"}}) {\n    username\n  }\n  myusername: profile (where: {username: {_eq: \"foobar\"}}) {\n    username\n  }\n}\n"
    },
    "generated_sql": {
      "profile": {
        "prepared_arguments": ["{\"x-hasura-role\":\"admin\"}", "%a%"],
        "query": "SELECT  coalesce(json_agg(\"root\" ), '[]' ) AS \"root\" FROM  (SELECT  row_to_json((SELECT  \"_1_e\"  FROM  (SELECT  \"_0_root.base\".\"username\" AS \"username\"       ) AS \"_1_e\"      ) ) AS \"root\" FROM  (SELECT  *  FROM \"public\".\"profile\"  WHERE ((\"public\".\"profile\".\"username\") LIKE ($2))     ) AS \"_0_root.base\"     LIMIT 10 ) AS \"_2_root\"      "
      },
      "myusername": {
        "prepared_arguments": ["{\"x-hasura-role\":\"admin\"}", "foobar"],
        "query": "SELECT  coalesce(json_agg(\"root\" ), '[]' ) AS \"root\" FROM  (SELECT  row_to_json((SELECT  \"_1_e\"  FROM  (SELECT  \"_0_root.base\".\"username\" AS \"username\"       ) AS \"_1_e\"      ) ) AS \"root\" FROM  (SELECT  *  FROM \"public\".\"profile\"  WHERE ((\"public\".\"profile\".\"username\") = ($2))     ) AS \"_0_root.base\"      ) AS \"_2_root\"      "
      }
    }
  }
}

The type of in the log with be query-log. All the details are nested under the detail key.

This log contains 3 important fields:

request_id: A unique ID for each request. If the client sends a x-request-id header then that is respected, otherwise a UUID is generated for each request. This is useful to correlate between http-log and query-log.
query: Contains the full GraphQL request including the variables and operation name.
generated_sql: this contains the generated SQL for GraphQL queries. For mutations and subscriptions this field will be null.

http-log structure¶

This is how the HTTP access logs look like:

On success response:

{
  "timestamp": "2019-05-30T23:40:24.654+0530",
  "level": "info",
  "type": "http-log",
  "detail": {
    "operation": {
      "query_execution_time": 0.009240042,
      "user_vars": {
        "x-hasura-role": "user"
      },
      "error": null,
      "request_id": "072b3617-6653-4fd5-b5ee-580e9d098c3d",
      "response_size": 105,
      "query": null
    },
    "http_info": {
      "status": 200,
      "http_version": "HTTP/1.1",
      "url": "/v1/graphql",
      "ip": "127.0.0.1",
      "method": "POST"
    }
  }
}

On error response:

{
  "timestamp": "2019-05-29T15:22:37.834+0530",
  "level": "error",
  "type": "http-log",
  "detail": {
    "operation": {
      "query_execution_time": 0.000656144,
      "user_vars": {
        "x-hasura-role": "user",
        "x-hasura-user-id": "1"
      },
      "error": {
        "path": "$.selectionSet.profile.selectionSet.usernamex",
        "error": "field \"usernamex\" not found in type: 'profile'",
        "code": "validation-failed"
      },
      "request_id": "072b3617-6653-4fd5-b5ee-580e9d098c3d",
      "response_size": 142,
      "query": {
        "variables": {
          "limit": 10
        },
        "operationName": "getProfile",
        "query": "query getProfile($limit: Int!) { profile(limit: $limit, where:{username: {_like: \"%a%\"}}) { usernamex} }"
      }
    },
    "http_info": {
      "status": 200,
      "http_version": "HTTP/1.1",
      "url": "/v1/graphql",
      "ip": "127.0.0.1",
      "method": "POST"
    }

}

The type in the log will be http-log for HTTP access/error log. This log contains basic information about the HTTP request and the GraphQL operation.

It has two important “keys” under the detail section - operation and http_info.

http_info lists various information regarding the HTTP request, e.g. IP address, URL path, HTTP status code etc.

operation lists various information regarding the GraphQL query/operation.

query_execution_time: the time taken to parse the GraphQL query (from JSON request), compile it to SQL with permissions and user session variables, and then executing it and fetching the results back from Postgres. The unit is in seconds.
user_vars: contains the user session variables. Or the x-hasura-* session variables inferred from the authorization mode.
request_id: A unique ID for each request. If the client sends a x-request-id header then that is respected, otherwise a UUID is generated for each request.
response_size: Size of the response in bytes.
error: optional. Will contain the error object when there is an error, otherwise this will be null. This key can be used to detect if there is an error in the request. The status code for error requests will be 200 on the v1/graphql endpoint.
query: optional. This will contain the GraphQL query object only when there is an error. On successful response this will be null.

websocket-log structure¶

This is how the Websocket logs look like:

On successful operation start:

{
  "timestamp": "2019-06-10T10:52:54.247+0530",
  "level": "info",
  "type": "websocket-log",
  "detail": {
    "event": {
      "type": "operation",
      "detail": {
        "request_id": "d2ede87d-5cb7-44b6-8736-1d898117722a",
        "operation_id": "1",
        "query": {
          "variables": {},
          "query": "subscription {\n  author {\n    name\n  }\n}\n"
        },
        "operation_type": {
          "type": "started"
        },
        "operation_name": null
      }
    },
    "connection_info": {
      "websocket_id": "f590dd18-75db-4602-8693-8150239df7f7",
      "jwt_expiry": null,
      "msg": null
    },
    "user_vars": {
      "x-hasura-role": "admin"
    }
  }
}

On operation stop:

{
  "timestamp": "2019-06-10T11:01:40.939+0530",
  "level": "info",
  "type": "websocket-log",
  "detail": {
    "event": {
      "type": "operation",
      "detail": {
        "request_id": null,
        "operation_id": "1",
        "query": null,
        "operation_type": {
          "type": "stopped"
        },
        "operation_name": null
      }
    },
    "connection_info": {
      "websocket_id": "7f782190-fd58-4305-a83f-8e17177b204e",
      "jwt_expiry": null,
      "msg": null
    },
    "user_vars": {
      "x-hasura-role": "admin"
    }
  }
}

On error:

{
  "timestamp": "2019-06-10T10:55:20.650+0530",
  "level": "error",
  "type": "websocket-log",
  "detail": {
    "event": {
      "type": "operation",
      "detail": {
        "request_id": "150e3e6a-e1a7-46ba-a9d4-da6b192a4005",
        "operation_id": "1",
        "query": {
          "variables": {},
          "query": "subscription {\n  author {\n    namex\n  }\n}\n"
        },
        "operation_type": {
          "type": "query_err",
          "detail": {
            "path": "$.selectionSet.author.selectionSet.namex",
            "error": "field \"namex\" not found in type: 'author'",
            "code": "validation-failed"
          }
        },
        "operation_name": null
      }
    },
    "connection_info": {
      "websocket_id": "49932ddf-e54d-42c6-bffb-8a57a1c6dcbe",
      "jwt_expiry": null,
      "msg": null
    },
    "user_vars": {
      "x-hasura-role": "admin"
    }
  }
}

Monitoring frameworks¶

You can integrate the logs emitted by Hasura GraphQL with external monitoring tools for better visibility as per your convenience.

For some examples, see Guides: Integrating with monitoring frameworks.

« previous | next »

Want to contribute or report missing content?

edit this page on github | contributing guidelines | report an issue

Hasura GraphQL engine is open source. See license