Default package

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. This structure provides data for the count and latency of individual field executions and thus only reflects operations for which field-level tracing occurred.

• optional StatsContext context = 1

• map<string, TypeStat> per_type_stat = 2

Used in: TypeStat

• string return_type = 3

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

• uint64 errors_count = 4

  Number of errors whose path is this field. Note that we assume that error tracking does *not* require field-level instrumentation so this *will* include errors from requests that don't contribute to the `observed_execution_count` field (and does not need to be scaled by field_execution_weight).

• uint64 observed_execution_count = 5

  Number of times that the resolver for this field is directly observed being executed.

• uint64 estimated_execution_count = 10

  Same as `count` but potentially scaled upwards if the server was only performing field-level instrumentation on a sampling of operations. For example, if the server randomly instruments 1% of requests for this operation, this number will be 100 times greater than `observed_execution_count`. (When aggregating a Trace into FieldStats, this number goes up by the trace's `field_execution_weight` for each observed field execution, while `observed_execution_count` above goes up by 1.)

• uint64 requests_with_errors_count = 6

  Number of times the resolver for this field is executed that resulted in at least one error. "Request" is a misnomer here as this corresponds to resolver calls, not overall operations. Like `errors_count` above, this includes all requests rather than just requests with field-level instrumentation.

• repeated sint64 latency_count = 9

  Duration histogram for the latency of this field. Note that it is scaled in the same way as estimated_execution_count so its "total count" might be greater than `observed_execution_count` and may not exactly equal `estimated_execution_count` due to rounding.

Used in: QueryLatencyStats

• map<string, PathErrorStats> children = 1

• uint64 errors_count = 4

• uint64 requests_with_errors_count = 5

Used in: ContextualizedQueryLatencyStats, ContextualizedStats

• repeated sint64 latency_count = 13

• uint64 request_count = 2

• uint64 cache_hits = 3

• uint64 persisted_query_hits = 4

• uint64 persisted_query_misses = 5

• repeated sint64 cache_latency_count = 14

• optional PathErrorStats root_error_stats = 7

• uint64 requests_with_errors_count = 8

• repeated sint64 public_cache_ttl_count = 15

• repeated sint64 private_cache_ttl_count = 16

• uint64 registered_operation_count = 11

• uint64 forbidden_operation_count = 12

• uint64 requests_without_field_instrumentation = 17

  The number of requests that were executed without field-level instrumentation (and thus do not contribute to `observed_execution_count` fields on this message's cousin-twice-removed FieldStats).

Used in: TracesAndStats

• repeated string field_names = 1

  Contains (eg) "email" for User.email:String!

• bool is_interface = 2

  True if this type is an interface.

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

• uint64 operation_count = 6

  Total number of operations processed during this period.

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 graph_ref = 12

  eg "mygraph@myvariant"

• 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 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_name = 2

• string client_version = 3

Used in: Trace.QueryPlanNode.FetchNode, TracesAndStats

• optional google.protobuf.Timestamp start_time = 4

  Wallclock time when the trace began.

  required

• optional google.protobuf.Timestamp end_time = 3

  Wallclock 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

• string client_version = 8

• 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?

• double field_execution_weight = 31

  Some servers don't do field-level instrumentation for every request and assign each request a "weight" for each request that they do instrument. When this trace is aggregated into field usage stats, it should count as this value towards the estimated_execution_count rather than just 1. This value should typically be at least 1. 0 is treated as 1 for backwards compatibility.

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.

• 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

  Wallclock 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 operation should either be described as a trace or as part of stats, but not both.

Used in: Report

• repeated Trace trace = 1

• repeated ContextualizedStats stats_with_context = 2

• map<string, ReferencedFieldsForType> referenced_fields_by_type = 4

  This describes the fields referenced in the operation. Note that this may include fields that don't show up in FieldStats (due to being interface fields, being nested under null fields or empty lists or non-matching fragments or `@include` or `@skip`, etc). It also may be missing fields that show up in FieldStats (as FieldStats will include the concrete object type for fields referenced via an interface type).

• repeated Trace internal_traces_contributing_to_stats = 3

  This field is used to validate that the algorithm used to construct `stats_with_context` matches similar algorithms in Apollo's servers. It is otherwise ignored and should not be included in reports.

Used in: ContextualizedStats, ContextualizedTypeStats

• map<string, FieldStat> per_field_stat = 3

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