package mdg.engine.proto

Get desktop application:
View/edit binary Protocol Buffers messages

• optional QueryLatencyStats query_latency_stats = 1

• optional StatsContext context = 2

Used in: TracesAndStats

• optional StatsContext context = 1

• optional QueryLatencyStats query_latency_stats = 2

• map<string, TypeStat> per_type_stat = 3

  Key is type name.

• optional StatsContext context = 1

• map<string, TypeStat> per_type_stat = 2

Used in: Type

• string name = 2

  required; eg "email" for User.email:String!

• string return_type = 3

  required; eg "String!" for User.email:String!

Used in: TypeStat

• string return_type = 3

  required; eg "String!" for User.email:String!

• uint64 errors_count = 4

• uint64 count = 5

• uint64 requests_with_errors_count = 6

• repeated int64 latency_count = 8

  Duration histogram; see docs/histograms.md

Used in: QueryLatencyStats

• map<string, PathErrorStats> children = 1

• uint64 errors_count = 4

• uint64 requests_with_errors_count = 5

Used in: ContextualizedQueryLatencyStats, ContextualizedStats

• repeated int64 latency_count = 1

• uint64 request_count = 2

• uint64 cache_hits = 3

• uint64 persisted_query_hits = 4

• uint64 persisted_query_misses = 5

• repeated int64 cache_latency_count = 6

• optional PathErrorStats root_error_stats = 7

• uint64 requests_with_errors_count = 8

• repeated int64 public_cache_ttl_count = 9

• repeated int64 private_cache_ttl_count = 10

• uint64 registered_operation_count = 11

• uint64 forbidden_operation_count = 12

This is the top-level message used by the new traces ingress. This is designed for the apollo-engine-reporting TypeScript agent and will eventually be documented as a public ingress API. This message consists solely of traces; the equivalent of the StatsReport is automatically generated server-side from this message. Agent should either send a trace or include it in the stats for every request in this report. Generally, buffering up until a large size has been reached (say, 4MB) or 5-10 seconds has passed is appropriate. This message used to be know as FullTracesReport, but got renamed since it isn't just for traces anymore

• optional ReportHeader header = 1

• map<string, TracesAndStats> traces_per_query = 5

  key is statsReportKey (# operationName\nsignature) Note that the nested traces will *not* have a signature or details.operationName (because the key is adequate). We also assume that traces don't have legacy_per_query_implicit_operation_name, and we don't require them to have details.raw_query (which would consume a lot of space and has privacy/data access issues, and isn't currently exposed by our app anyway).

• optional google.protobuf.Timestamp end_time = 2

  This is the time that the requests in this trace are considered to have taken place If this field is not present the max of the end_time of each trace will be used instead. If there are no traces and no end_time present the report will not be able to be processed. Note: This will override the end_time from traces.

  required if no traces in this message

The `service` value embedded within the header key is not guaranteed to contain an actual service, and, in most cases, the service information is trusted to come from upstream processing. If the service _is_ specified in this header, then it is checked to match the context that is reporting it. Otherwise, the service information is deduced from the token context of the reporter and then sent along via other mechanisms (in Kafka, the `ReportKafkaKey). The other information (hostname, agent_version, etc.) is sent by the Apollo Engine Reporting agent, but we do not currently save that information to any of our persistent storage.

Used in: Report

• string hostname = 5

  eg "host-01.example.com"

• string agent_version = 6

  eg "engineproxy 0.1.0"

  required

• string service_version = 7

  eg "prod-4279-20160804T065423Z-5-g3cf0aa8" (taken from `git describe --tags`)

• string runtime_version = 8

  eg "node v4.6.0"

• string uname = 9

  eg "Linux box 4.6.5-1-ec2 #1 SMP Mon Aug 1 02:31:38 PDT 2016 x86_64 GNU/Linux"

• string schema_tag = 10

  eg "current", "prod"

• string executable_schema_id = 11

  An id that is used to represent the schema to Apollo Graph Manager Using this in place of what used to be schema_hash, since that is no longer attached to a schema in the backend.

Used in: ContextualizedQueryLatencyStats, ContextualizedStats, ContextualizedTypeStats

• string client_reference_id = 1

• string client_name = 2

• string client_version = 3

Used in: Trace.QueryPlanNode.FetchNode, TracesAndStats

• optional google.protobuf.Timestamp start_time = 4

  Wall clock time when the trace began.

  required

• optional google.protobuf.Timestamp end_time = 3

  Wall clock time when the trace ended.

  required

• uint64 duration_ns = 11

  High precision duration of the trace; may not equal end_time-start_time (eg, if your machine's clock changed during the trace).

  required

• optional Trace.Node root = 14

  A tree containing information about all resolvers run directly by this service, including errors.

• string signature = 19

  In addition to details.raw_query, we include a "signature" of the query, which can be normalized: for example, you may want to discard aliases, drop unused operations and fragments, sort fields, etc. The most important thing here is that the signature match the signature in StatsReports. In StatsReports signatures show up as the key in the per_query map (with the operation name prepended). The signature should be a valid GraphQL query. All traces must have a signature; if this Trace is in a FullTracesReport that signature is in the key of traces_per_query rather than in this field. Engineproxy provides the signature in legacy_signature_needs_resigning instead.

• string unexecutedOperationBody = 27

  Optional: when GraphQL parsing or validation against the GraphQL schema fails, these fields can include reference to the operation being sent for users to dig into the set of operations that are failing validation.

• string unexecutedOperationName = 28

• optional Trace.Details details = 6

• string client_name = 7

  Note: engineproxy always sets client_name, client_version, and client_address to "none". apollo-engine-reporting allows for them to be set by the user.

• string client_version = 8

• string client_address = 9

• string client_reference_id = 23

• optional Trace.HTTP http = 10

• optional Trace.CachePolicy cache_policy = 18

• optional Trace.QueryPlanNode query_plan = 26

  If this Trace was created by a gateway, this is the query plan, including sub-Traces for federated services. Note that the 'root' tree on the top-level Trace won't contain any resolvers (though it could contain errors that occurred in the gateway itself).

• bool full_query_cache_hit = 20

  Was this response served from a full query response cache? (In that case the node tree will have no resolvers.)

• bool persisted_query_hit = 21

  Was this query specified successfully as a persisted query hash?

• bool persisted_query_register = 22

  Did this query contain both a full query string and a persisted query hash? (This typically means that a previous request was rejected as an unknown persisted query.)

• bool registered_operation = 24

  Was this operation registered and a part of the safelist?

• bool forbidden_operation = 25

  Was this operation forbidden due to lack of safelisting?

• string legacy_signature_needs_resigning = 5

  Older agents (eg the Go engineproxy) relied to some degree on the Engine backend to run their own semi-compatible implementation of a specific variant of query signatures. The backend does not do this for new agents (which set the above 'signature' field). It used to still "re-sign" signatures from engineproxy, but we've now simplified the backend to no longer do this. Deprecated and ignored in FullTracesReports.

Used in: Trace, Node

• CachePolicy.Scope scope = 1

• int64 max_age_ns = 2

  use 0 for absent, -1 for 0

Used in: CachePolicy

• UNKNOWN = 0

• PUBLIC = 1

• PRIVATE = 2

Used in: Trace

• map<string, string> variables_json = 4

  The variables associated with this query (unless the reporting agent is configured to keep them all private). Values are JSON: ie, strings are enclosed in double quotes, etc. The value of a private variable is the empty string.

• map<string, bytes> deprecated_variables = 1

  Deprecated. Engineproxy did not encode variable values as JSON, so you couldn't tell numbers from numeric strings. Send variables_json instead.

• string operation_name = 3

  This is deprecated and only used for legacy applications don't include this in traces inside a FullTracesReport; the operation name for these traces comes from the key of the traces_per_query map.

Used in: Node

• string message = 1

  required

• repeated Location location = 2

• uint64 time_ns = 3

• string json = 4

Used in: Trace

• HTTP.Method method = 1

• string host = 2

• string path = 3

• map<string, HTTP.Values> request_headers = 4

  Should exclude manual blacklist ("Auth" by default)

• map<string, HTTP.Values> response_headers = 5

• uint32 status_code = 6

• bool secure = 8

  TLS was used

• string protocol = 9

  by convention "HTTP/1.0", "HTTP/1.1", "HTTP/2" or "h2"

Used in: HTTP

• UNKNOWN = 0

• OPTIONS = 1

• GET = 2

• HEAD = 3

• POST = 4

• PUT = 5

• DELETE = 6

• TRACE = 7

• CONNECT = 8

• PATCH = 9

Used in: HTTP

• repeated string value = 1

Used in: Error

• uint32 line = 1

• uint32 column = 2

We store information on each resolver execution as a Node on a tree. The structure of the tree corresponds to the structure of the GraphQL response; it does not indicate the order in which resolvers were invoked. Note that nodes representing indexes (and the root node) don't contain all Node fields (eg types and times).

Used in: Trace

• oneof id

  The name of the field (for Nodes representing a resolver call) or the index in a list (for intermediate Nodes representing elements of a list). field_name is the name of the field as it appears in the GraphQL response: ie, it may be an alias. (In that case, the original_field_name field holds the actual field name from the schema.) In any context where we're building up a path, we use the response_name rather than the original_field_name.

  • string response_name = 1

  • uint32 index = 2

• string original_field_name = 14

• string type = 3

  The field's return type; e.g. "String!" for User.email:String!

• string parent_type = 13

  The field's parent type; e.g. "User" for User.email:String!

• optional CachePolicy cache_policy = 5

• uint64 start_time = 8

  relative to the trace's start_time, in ns

• uint64 end_time = 9

  relative to the trace's start_time, in ns

• repeated Error error = 11

• repeated Node child = 12

represents a node in the query plan, under which there is a trace tree for that service fetch. In particular, each fetch node represents a call to an implementing service, and calls to implementing services may not be unique. See https://github.com/apollographql/apollo-server/blob/main/packages/apollo-gateway/src/QueryPlan.ts for more information and details.

Used in: Trace, QueryPlanNode.FlattenNode, QueryPlanNode.ParallelNode, QueryPlanNode.SequenceNode

• oneof node

  • QueryPlanNode.SequenceNode sequence = 1

  • QueryPlanNode.ParallelNode parallel = 2

  • QueryPlanNode.FetchNode fetch = 3

  • QueryPlanNode.FlattenNode flatten = 4

This represents a node to send an operation to an implementing service

Used in: QueryPlanNode

• string service_name = 1

  XXX When we want to include more details about the sub-operation that was executed against this service, we should include that here in each fetch node. This might include an operation signature, requires directive, reference resolutions, etc.

• bool trace_parsing_failed = 2

• optional Trace trace = 3

  This Trace only contains start_time, end_time, duration_ns, and root; all timings were calculated **on the federated service**, and clock skew will be handled by the ingress server.

• uint64 sent_time_offset = 4

  relative to the outer trace's start_time, in ns, measured in the gateway.

• optional google.protobuf.Timestamp sent_time = 5

  Wall clock times measured in the gateway for when this operation was sent and received.

• optional google.protobuf.Timestamp received_time = 6

This node represents a way to reach into the response path and attach related entities. XXX Flatten is really not the right name and this node may be renamed in the query planner.

Used in: QueryPlanNode

• repeated ResponsePathElement response_path = 1

• optional QueryPlanNode node = 2

This represents a set of nodes to be executed in parallel by the Gateway executor

Used in: QueryPlanNode

• repeated QueryPlanNode nodes = 1

Used in: FlattenNode

• oneof id

  • string field_name = 1

  • uint32 index = 2

This represents a set of nodes to be executed sequentially by the Gateway executor

Used in: QueryPlanNode

• repeated QueryPlanNode nodes = 1

A sequence of traces and stats. An individual trace should either be counted as a stat or trace

Used in: Report

• repeated Trace trace = 1

• repeated ContextualizedStats stats_with_context = 2

• string name = 1

  required; eg "User" for User.email:String!

• repeated Field field = 2

Used in: ContextualizedStats, ContextualizedTypeStats

• map<string, FieldStat> per_field_stat = 3

  Key is (eg) "email" for User.email:String!