This is an automated email from the ASF dual-hosted git repository. abesto pushed a commit to branch asf-site in repository https://gitbox.apache.org/repos/asf/incubator-zipkin-website.git
commit 549652e264506fd5fc5f4afd0ca8a79204549f55 Author: jenkins <[email protected]> AuthorDate: Fri May 10 14:05:59 2019 +0000 force adds zipkin-api --- zipkin-api/zipkin-api.yaml | 441 +++++++++++++++++++++++++++++++++++++ zipkin-api/zipkin.proto | 237 ++++++++++++++++++++ zipkin-api/zipkin2-api.yaml | 521 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 1199 insertions(+) diff --git a/zipkin-api/zipkin-api.yaml b/zipkin-api/zipkin-api.yaml new file mode 100644 index 0000000..2f4a190 --- /dev/null +++ b/zipkin-api/zipkin-api.yaml @@ -0,0 +1,441 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +swagger: "2.0" +info: + version: "1.0.0" + title: Zipkin API + description: | + Zipkin's Query api is rooted at `api/v1`, on a host that by default listens + on port 9411. It primarily serves the zipkin-ui, although it includes a POST + endpoint that can receive spans. +host: localhost:9411 +basePath: /api/v1 +schemes: + - http + - https +consumes: + - application/json +produces: + - application/json +paths: + /services: + get: + description: | + Returns a list of all service names associated with annotations. + responses: + '200': + description: Succes + schema: + type: array + items: + type: string + '400': + description: Bad Request Error + /spans: + get: + description: Get all the span names logged by a particular service + parameters: + - name: serviceName + in: query + required: true + description: | + Ex zipkin-server (required) - service that logged an annotation in a + trace. The /services endpoint enumerates possible input values. + type: string + responses: + '200': + description: OK + schema: + type: array + items: + type: string + '400': + description: Bad Request Error + post: + description: | + Uploads a list of spans encoded per content-type, for example json + or thrift (TBinaryProtocol big-endian). + consumes: + - application/json + - application/x-thrift + produces: [] + parameters: + - name: span + in: body + description: A list of spans that belong to any trace. + required: true + schema: + $ref: "#/definitions/ListOfSpans" + responses: + '202': + description: Accepted + /traces: + get: + description: | + Invoking this request retrieves traces matching the below filters. + + Results should be filtered against endTs, subject to limit and + lookback. For example, if endTs is 10:20 today, limit is 10, and + lookback is 7 days, traces returned should be those nearest to 10:20 + today, not 10:20 a week ago. + + Time units of endTs and lookback are milliseconds as opposed to + microseconds, the grain of Span.timestamp. Milliseconds is a more + familiar and supported granularity for query, index and windowing + functions + parameters: + - name: serviceName + in: query + required: false + description: | + Ex zipkin-server - service that logged an annotation in a trace. + Required when constraining on parameters except time and duration. + The /services endpoint enumerates possible input values. + type: string + - name: spanName + in: query + required: false + description: | + Ex my_span_name - name of a span in a trace. + Only return traces that contains spans with this name. + type: string + - name: annotationQuery + in: query + type: string + required: false + description: | + Ex. `http.uri=/foo and retried` - If key/value (has an `=`), + constrains against Span.binaryAnnotations of time string. If just + a word, constrains against Span.annotations. Any values are AND + against eachother. This means a span in the trace must match all of + these. + - name: minDuration + in: query + type: integer + description: | + Ex. 100000 (for 100ms). Only return traces whose `Span.duration` is + greater than or equal to minDuration microseconds. + - name: maxDuration + in: query + type: integer + description: | + Only return traces whose Span.duration is less than or equal to + `maxDuration` microseconds. Only valid with minDuration. + - name: endTs + in: query + type: integer + format: int64 + description: | + Only return traces where all Span.timestamp are at or before this + time in epoch milliseconds. Defaults to current time. + - name: lookback + type: integer + format: int64 + in: query + description: | + Only return traces where all Span.timestamp are at or after + (`endTs - * lookback`) in milliseconds. Defaults to `endTs`, limited + to a system parameter `QUERY_LOOKBACK`. + - name: limit + in: query + default: 10 + type: integer + description: | + Maximum number of traces to return. Defaults to 10 + responses: + '200': + description: OK + schema: + $ref: "#/definitions/ListOfTraces" + /trace/{traceId}: + get: + parameters: + - name: traceId + in: path + required: true + description: the 64 or 128-bit big endian, hex-encoded id of the trace as a path parameter. + type: string + - name: raw + in: query + required: false + description: | + Note this flag has no value. Ex. /trace/{traceId}?raw + + Normally, the trace endpoint cleans trace data. For example, it merges + spans by id, adds missing timestamp or duration, corrects clock skew.. + + Specifying this flag is a debug case, when you are debugging zipkin + logic or zipkin instrumentation, and want to see the input to these + adjusters. For example, this might explain or rule out clock skew. + type: boolean + responses: + '200': + description: OK + schema: + $ref: "#/definitions/Trace" + '404': + description: "`traceId` not found" + /dependencies: + get: + description: | + Returns dependency links derived from spans. + + Span names are in lowercase, rpc method for example. Conventionally, + when the span name isn't known, name = "unknown". + parameters: + - name: endTs + in: query + description: | + Only return links from spans where `Span.timestamp` are at or before + this time in epoch milliseconds. + required: true + type: integer + format: int64 + - name: lookback + in: query + description: | + Only return links from spans where all Span.timestamp are at or after + (`endTs - * lookback`) in milliseconds. Defaults to `endTs`, limited + to a system parameter `QUERY_LOOKBACK`. + type: integer + format: int64 + responses: + '200': + description: OK + schema: + type: array + title: ListOfDependencyLinks + items: + $ref: "#/definitions/DependencyLink" +definitions: + Endpoint: + type: object + title: Endpoint + description: The network context of a node in the service graph + required: + - serviceName + properties: + serviceName: + type: string + description: | + Lower-case label of this node in the service graph, such as "favstar". Set + to empty string if unknown. + + This is a primary label for trace lookup and aggregation, so it should be + intuitive and consistent. Many use a name from service discovery. + ipv4: + type: string + format: ipv4 + description: | + The text representation of the primary IPv4 address associated with this + connection. Ex. 192.168.99.100 Absent if unknown. + ipv6: + type: string + format: ipv6 + description: | + The text representation of the primary IPv6 address associated with a + connection. Ex. 2001:db8::c001 Absent if unknown. + + Prefer using the ipv4 field for mapped addresses. + port: + type: integer + description: | + Depending on context, this could be a listen port or the client-side of a + socket. Absent if unknown. Please don't set to zero. + Annotation: + title: Annotation + type: object + required: + - timestamp + - value + description: | + Associates an event that explains latency with a timestamp. + Unlike log statements, annotations are often codes. Ex. "sr" for ServerReceive + properties: + timestamp: + type: integer + description: | + Epoch **microseconds** of this event. + + For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC + + This value should be set directly by instrumentation, using the most precise + value possible. For example, gettimeofday or multiplying epoch millis by 1000. + value: + type: string + description: | + Usually a short tag indicating an event, like "sr" + + While possible to add larger data, such as garbage collection details, low + cardinality event names both keep the size of spans down and also are easy + to search against. + endpoint: + $ref: "#/definitions/Endpoint" + description: | + The host that recorded this span, primarily for query by service name. + + Instrumentation should always record this. Usually, absent implies late + data. The IP address corresponding to this is usually the site local or + advertised service address. When present, the port indicates the listen + port. + BinaryAnnotation: + title: BinaryAnnotation + type: object + required: + - key + - value + description: | + Adds context to a span, for search, viewing and analysis. + + For example, a key "your_app.version" would let you lookup traces by version. + A tag "sql.query" isn't searchable, but it can help in debugging when viewing + a trace. + properties: + key: + type: string + value: + type: string + endpoint: + $ref: "#/definitions/Endpoint" + description: | + The host that recorded this span, primarily for query by service name. + + There is an exception, when the key is "sa", "ca" or "ma" this is an + address annotation. In such case, the endpoint is not what recorded the + span, rather the remote address. The value field is set to boolean true + in this case. This feature was refactored in v2 format as "remoteEndpoint" + ListOfSpans: + title: ListOfSpans + description: 'A list of spans with possibly different trace ids, in no particular order' + type: array + items: + $ref: "#/definitions/Span" + Trace: + title: Trace + type: array + description: 'List of spans who have the same trace id. Spans in the trace, and annotations in a span are sorted ascending by timestamp. ie first event should be first in the spans list.' + items: + $ref: "#/definitions/Span" + ListOfTraces: + title: ListOfTraces + type: array + items: + $ref: "#/definitions/Trace" + Span: + title: Span + type: object + required: + - traceId + - id + - name + properties: + traceId: + type: string + maxLength: 32 + minLength: 16 + pattern: "[a-z0-9]{16,32}" + description: | + Randomly generated, unique identifier for a trace, set on all spans within it. + + Encoded as 16 or 32 lowercase hex characters in big endian byte order, + corresponding to 64 or 128 bits, + For example, a 128bit trace ID looks like 4e441824ec2b6a44ffdc9bb9a6453df3 + name: + type: string + description: | + The logical operation this span represents in lowercase (e.g. rpc method). + Set to empty string if unknown. + + As these are lookup labels, take care to ensure names are low cardinality. + For example, do not embed variables into the name. + parentId: + type: string + pattern: "[a-z0-9]{16}" + maxLength: 16 + minLength: 16 + description: 'The parent span ID or absent if this the root span in a trace.' + id: + type: string + maxLength: 16 + minLength: 16 + pattern: "[a-z0-9]{16}" + description: | + Unique 64bit identifier for this operation within the trace. + + Encoded as 16 lowercase hex characters. For example ffdc9bb9a6453df3 + timestamp: + type: integer + format: int64 + description: | + Epoch microseconds of the start of this span, possibly absent if + incomplete. + + For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC + + This value should be set directly by instrumentation, using the most + precise value possible. For example, gettimeofday or multiplying epoch + millis by 1000. + + There are three known edge-cases where this could be reported absent. + * A span was allocated but never started (ex not yet received a timestamp) + * The span's start event was lost + * Data about a completed span (ex tags) were sent after the fact + duration: + type: integer + format: int64 + minimum: 1 + description: | + Duration in **microseconds** of the critical path, if known. Durations of less + than one are rounded up. Duration of children can be longer than their + parents due to asynchronous operations. + + For example 150 milliseconds is 150000 microseconds. + debug: + type: boolean + description: | + True is a request to store this span even if it overrides sampling policy. + + This is true when the `X-B3-Flags` header has a value of 1. + annotations: + title: ListOfAnnotations + type: array + description: 'Associates events that explain latency with the time they happened.' + items: + $ref: '#/definitions/Annotation' + binaryAnnotations: + title: ListOfBinaryAnnotations + type: array + description: 'Binary Annotations are tags that give your span context for search, viewing and analysis.' + items: + $ref: '#/definitions/BinaryAnnotation' + DependencyLink: + title: DependencyLink + type: object + required: + - parent + - child + - callCount + properties: + parent: + type: string + child: + type: string + callCount: + type: integer + errorCount: + type: integer diff --git a/zipkin-api/zipkin.proto b/zipkin-api/zipkin.proto new file mode 100644 index 0000000..9e65112 --- /dev/null +++ b/zipkin-api/zipkin.proto @@ -0,0 +1,237 @@ +// +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. +// +syntax = "proto3"; + +package zipkin.proto3; + +// In Java, the closest model type to this proto is in the "zipkin2" package +option java_package = "zipkin2.proto3"; +option java_multiple_files = true; + +// A span is a single-host view of an operation. A trace is a series of spans +// (often RPC calls) which nest to form a latency tree. Spans are in the same +// trace when they share the same trace ID. The parent_id field establishes the +// position of one span in the tree. +// +// The root span is where parent_id is Absent and usually has the longest +// duration in the trace. However, nested asynchronous work can materialize as +// child spans whose duration exceed the root span. +// +// Spans usually represent remote activity such as RPC calls, or messaging +// producers and consumers. However, they can also represent in-process +// activity in any position of the trace. For example, a root span could +// represent a server receiving an initial client request. A root span could +// also represent a scheduled job that has no remote context. +// +// Encoding notes: +// +// Epoch timestamp are encoded fixed64 as varint would also be 8 bytes, and more +// expensive to encode and size. Duration is stored uint64, as often the numbers +// are quite small. +// +// Default values are ok, as only natural numbers are used. For example, zero is +// an invalid timestamp and an invalid duration, false values for debug or shared +// are ignorable, and zero-length strings also coerce to null. +// +// The next id is 14. +// +// Note fields up to 15 take 1 byte to encode. Take care when adding new fields +// https://developers.google.com/protocol-buffers/docs/proto3#assigning-tags +message Span { + // Randomly generated, unique identifier for a trace, set on all spans within + // it. + // + // This field is required and encoded as 8 or 16 bytes, in big endian byte + // order. + bytes trace_id = 1; + // The parent span ID or absent if this the root span in a trace. + bytes parent_id = 2; + // Unique identifier for this operation within the trace. + // + // This field is required and encoded as 8 opaque bytes. + bytes id = 3; + // When present, kind clarifies timestamp, duration and remote_endpoint. When + // absent, the span is local or incomplete. Unlike client and server, there + // is no direct critical path latency relationship between producer and + // consumer spans. + enum Kind { + // Default value interpreted as absent. + SPAN_KIND_UNSPECIFIED = 0; + // The span represents the client side of an RPC operation, implying the + // following: + // + // timestamp is the moment a request was sent to the server. + // duration is the delay until a response or an error was received. + // remote_endpoint is the server. + CLIENT = 1; + // The span represents the server side of an RPC operation, implying the + // following: + // + // timestamp is the moment a client request was received. + // duration is the delay until a response was sent or an error. + // remote_endpoint is the client. + SERVER = 2; + // The span represents production of a message to a remote broker, implying + // the following: + // + // timestamp is the moment a message was sent to a destination. + // duration is the delay sending the message, such as batching. + // remote_endpoint is the broker. + PRODUCER = 3; + // The span represents consumption of a message from a remote broker, not + // time spent servicing it. For example, a message processor would be an + // in-process child span of a consumer. Consumer spans imply the following: + // + // timestamp is the moment a message was received from an origin. + // duration is the delay consuming the message, such as from backlog. + // remote_endpoint is the broker. + CONSUMER = 4; + } + // When present, used to interpret remote_endpoint + Kind kind = 4; + // The logical operation this span represents in lowercase (e.g. rpc method). + // Leave absent if unknown. + // + // As these are lookup labels, take care to ensure names are low cardinality. + // For example, do not embed variables into the name. + string name = 5; + // Epoch microseconds of the start of this span, possibly absent if + // incomplete. + // + // For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC + // + // This value should be set directly by instrumentation, using the most + // precise value possible. For example, gettimeofday or multiplying epoch + // millis by 1000. + // + // There are three known edge-cases where this could be reported absent. + // - A span was allocated but never started (ex not yet received a timestamp) + // - The span's start event was lost + // - Data about a completed span (ex tags) were sent after the fact + fixed64 timestamp = 6; + // Duration in microseconds of the critical path, if known. Durations of less + // than one are rounded up. Duration of children can be longer than their + // parents due to asynchronous operations. + // + // For example 150 milliseconds is 150000 microseconds. + uint64 duration = 7; + // The host that recorded this span, primarily for query by service name. + // + // Instrumentation should always record this. Usually, absent implies late + // data. The IP address corresponding to this is usually the site local or + // advertised service address. When present, the port indicates the listen + // port. + Endpoint local_endpoint = 8; + // When an RPC (or messaging) span, indicates the other side of the + // connection. + // + // By recording the remote endpoint, your trace will contain network context + // even if the peer is not tracing. For example, you can record the IP from + // the "X-Forwarded-For" header or the service name and socket of a remote + // peer. + Endpoint remote_endpoint = 9; + // Associates events that explain latency with the time they happened. + repeated Annotation annotations = 10; + // Tags give your span context for search, viewing and analysis. + // + // For example, a key "your_app.version" would let you lookup traces by + // version. A tag "sql.query" isn't searchable, but it can help in debugging + // when viewing a trace. + map<string, string> tags = 11; + // True is a request to store this span even if it overrides sampling policy. + // + // This is true when the "X-B3-Flags" header has a value of 1. + bool debug = 12; + // True if we are contributing to a span started by another tracer (ex on a + // different host). + bool shared = 13; +} + +// The network context of a node in the service graph. +// +// The next id is 5. +message Endpoint { + // Lower-case label of this node in the service graph, such as "favstar". + // Leave absent if unknown. + // + // This is a primary label for trace lookup and aggregation, so it should be + // intuitive and consistent. Many use a name from service discovery. + string service_name = 1; + // 4 byte representation of the primary IPv4 address associated with this + // connection. Absent if unknown. + bytes ipv4 = 2; + // 16 byte representation of the primary IPv6 address associated with this + // connection. Absent if unknown. + // + // Prefer using the ipv4 field for mapped addresses. + bytes ipv6 = 3; + // Depending on context, this could be a listen port or the client-side of a + // socket. Absent if unknown. + int32 port = 4; +} + +// Associates an event that explains latency with a timestamp. +// Unlike log statements, annotations are often codes. Ex. "ws" for WireSend +// +// The next id is 3. +message Annotation { + // Epoch microseconds of this event. + // + // For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC + // + // This value should be set directly by instrumentation, using the most + // precise value possible. For example, gettimeofday or multiplying epoch + // millis by 1000. + fixed64 timestamp = 1; + // Usually a short tag indicating an event, like "error" + // + // While possible to add larger data, such as garbage collection details, low + // cardinality event names both keep the size of spans down and also are easy + // to search against. + string value = 2; +} + +// A list of spans with possibly different trace ids, in no particular order. +// +// This is used for all transports: POST, Kafka messages etc. No other fields +// are expected, This message facilitates the mechanics of encoding a list, as +// a field number is required. The name of this type is the same in the OpenApi +// aka Swagger specification. https://zipkin.io/zipkin-api/#/default/post_spans +message ListOfSpans { + repeated Span spans = 1; +} + +// Response for SpanService/Report RPC. This response currently does not return +// any information beyond indicating that the request has finished. That said, +// it may be extended in the future. +message ReportResponse { +} + +// SpanService allows reporting spans using gRPC, as opposed to HTTP POST +// reporting. Implementations are asynchronous and may drop spans for reasons +// of sampling or storage availability. While this is primarily used to store +// spans, other operations may take place such as aggregation of service +// dependencies or data cleaning. +service SpanService { + + // Report the provided spans to the collector. Analogous to the HTTP POST + // /api/v2/spans endpoint. Spans are not required to be complete or belonging + // to the same trace. + rpc Report(ListOfSpans) returns (ReportResponse) {} +} diff --git a/zipkin-api/zipkin2-api.yaml b/zipkin-api/zipkin2-api.yaml new file mode 100644 index 0000000..9d25da7 --- /dev/null +++ b/zipkin-api/zipkin2-api.yaml @@ -0,0 +1,521 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +swagger: "2.0" +info: + version: "1.0.0" + title: Zipkin API + description: | + Zipkin's v2 api currently includes a POST endpoint that can receive spans. +host: localhost:9411 +basePath: /api/v2 +schemes: + - http + - https +consumes: + - application/json +paths: + /services: + get: + description: | + Returns a list of all service names associated with span endpoints. + responses: + '200': + description: Succes + schema: + type: array + items: + type: string + '400': + description: Bad Request Error + /spans: + get: + description: Get all the span names recorded by a particular service + parameters: + - name: serviceName + in: query + required: true + description: | + Ex favstar (required) - Lower-case label of a node in the service + graph. The /services endpoint enumerates possible input values. + type: string + responses: + '200': + description: OK + schema: + type: array + items: + type: string + '400': + description: Bad Request Error + post: + description: | + Uploads a list of spans encoded per content-type, for example json. + consumes: + - application/json + - application/x-protobuf + produces: [] + parameters: + - name: spans + in: body + description: A list of spans that belong to any trace. + required: true + schema: + $ref: "#/definitions/ListOfSpans" + responses: + '202': + description: Accepted + /traces: + get: + description: | + Invoking this request retrieves traces matching the below filters. + + Results should be filtered against endTs, subject to limit and + lookback. For example, if endTs is 10:20 today, limit is 10, and + lookback is 7 days, traces returned should be those nearest to 10:20 + today, not 10:20 a week ago. + + Time units of endTs and lookback are milliseconds as opposed to + microseconds, the grain of Span.timestamp. Milliseconds is a more + familiar and supported granularity for query, index and windowing + functions + parameters: + - name: serviceName + in: query + required: false + description: | + Ex favstar (required) - Lower-case label of a node in the service + graph. The /services endpoint enumerates possible input values. + type: string + - name: spanName + in: query + required: false + description: | + Ex get - name of a span in a trace. + Only return traces that contains spans with this name. + type: string + - name: annotationQuery + in: query + type: string + required: false + description: | + Ex. `http.uri=/foo and retried` - If key/value (has an `=`), + constrains against Span.tags entres. If just a word, constrains + against Span.annotations[].value or Span.tags[].key. Any values are + AND against eachother. This means a span in the trace must match + all of these. + - name: minDuration + in: query + type: integer + description: | + Ex. 100000 (for 100ms). Only return traces whose `Span.duration` is + greater than or equal to minDuration microseconds. + - name: maxDuration + in: query + type: integer + description: | + Only return traces whose Span.duration is less than or equal to + `maxDuration` microseconds. Only valid with minDuration. + - name: endTs + in: query + type: integer + format: int64 + description: | + Only return traces where all Span.timestamp are at or before this + time in epoch milliseconds. Defaults to current time. + - name: lookback + type: integer + format: int64 + in: query + description: | + Only return traces where all Span.timestamp are at or after (endTs + - * lookback) in milliseconds. Defaults to endTs, limited to a + system parameter QUERY_LOOKBACK + - name: limit + in: query + default: 10 + type: integer + description: | + Maximum number of traces to return. Defaults to 10 + responses: + '200': + description: OK + schema: + $ref: "#/definitions/ListOfTraces" + /trace/{traceId}: + get: + parameters: + - name: traceId + in: path + required: true + type: string + maxLength: 32 + minLength: 16 + pattern: "[a-z0-9]{16,32}" + description: | + Trace identifier, set on all spans within it. + + Encoded as 16 or 32 lowercase hex characters corresponding to 64 or 128 bits. + For example, a 128bit trace ID looks like 4e441824ec2b6a44ffdc9bb9a6453df3 + responses: + '200': + description: OK + schema: + $ref: "#/definitions/Trace" + '404': + description: "`traceId` not found" + /dependencies: + get: + description: | + Returns service links derived from spans. + parameters: + - name: endTs + in: query + description: | + only return links from spans where `Span.timestamp` are at or before + this time in epoch milliseconds. + required: true + type: integer + format: int64 + - name: lookback + in: query + description: | + only return links where all Span.timestamp are at or after + (`endTs - * lookback`) in milliseconds. Defaults to `endTs`, limited + to a system parameter `QUERY_LOOKBACK` + type: integer + format: int64 + responses: + '200': + description: OK + schema: + type: array + title: ListOfDependencyLinks + items: + $ref: "#/definitions/DependencyLink" + /autocompleteKeys: + get: + description: | + Returns a subset of keys from Span.tags configured for value autocompletion. + This helps sites populate common keys into the annotationQuery parameter of the + /traces endpoint. For example, a UI can allow users to select site-specific + keys from a drop-down as opposed to typing them in manually. This helps guide + users towards the more correct keys and avoids typos or formatting problems. + responses: + '200': + description: Success is a list of site-specific keys, such as environment. + schema: + type: array + items: + type: string + '400': + description: Bad Request Error + /autocompleteValues: + get: + description: | + Returns all known values of Span.tags for the given autocomplete key. Refer + to the description of /autocompleteKeys for the use case. + parameters: + - name: key + in: query + required: true + description: Name of the autocomplete key from the /autocompleteKeys endpoint. + type: string + responses: + '200': + description: | + Success result is empty when there are no values or the key was not + configured. + schema: + type: array + items: + type: string + '400': + description: Bad Request Error + +definitions: + Endpoint: + type: object + title: Endpoint + description: The network context of a node in the service graph + properties: + serviceName: + type: string + description: | + Lower-case label of this node in the service graph, such as "favstar". Leave + absent if unknown. + + This is a primary label for trace lookup and aggregation, so it should be + intuitive and consistent. Many use a name from service discovery. + ipv4: + type: string + format: ipv4 + description: | + The text representation of the primary IPv4 address associated with this + connection. Ex. 192.168.99.100 Absent if unknown. + ipv6: + type: string + format: ipv6 + description: | + The text representation of the primary IPv6 address associated with a + connection. Ex. 2001:db8::c001 Absent if unknown. + + Prefer using the ipv4 field for mapped addresses. + port: + type: integer + description: | + Depending on context, this could be a listen port or the client-side of a + socket. Absent if unknown. Please don't set to zero. + Annotation: + title: Annotation + type: object + description: | + Associates an event that explains latency with a timestamp. + Unlike log statements, annotations are often codes. Ex. "ws" for WireSend + + Zipkin v1 core annotations such as "cs" and "sr" have been replaced with + Span.Kind, which interprets timestamp and duration. + required: + - timestamp + - value + properties: + timestamp: + type: integer + description: | + Epoch **microseconds** of this event. + + For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC + + This value should be set directly by instrumentation, using the most precise + value possible. For example, gettimeofday or multiplying epoch millis by 1000. + value: + type: string + description: | + Usually a short tag indicating an event, like "error" + + While possible to add larger data, such as garbage collection details, low + cardinality event names both keep the size of spans down and also are easy + to search against. + Tags: + type: object + title: Tags + description: | + Adds context to a span, for search, viewing and analysis. + + For example, a key "your_app.version" would let you lookup traces by version. + A tag "sql.query" isn't searchable, but it can help in debugging when viewing + a trace. + additionalProperties: + type: string + ListOfSpans: + title: ListOfSpans + description: 'A list of spans with possibly different trace ids, in no particular order' + type: array + items: + $ref: "#/definitions/Span" + Trace: + title: Trace + type: array + description: 'List of spans who have the same trace ID.' + items: + $ref: "#/definitions/Span" + ListOfTraces: + title: ListOfTraces + type: array + items: + $ref: "#/definitions/Trace" + Span: + title: Span + description: | + A span is a single-host view of an operation. A trace is a series of spans + (often RPC calls) which nest to form a latency tree. Spans are in the same + trace when they share the same trace ID. The parent_id field establishes the + position of one span in the tree. + + The root span is where parent_id is Absent and usually has the longest + duration in the trace. However, nested asynchronous work can materialize as + child spans whose duration exceed the root span. + + Spans usually represent remote activity such as RPC calls, or messaging + producers and consumers. However, they can also represent in-process + activity in any position of the trace. For example, a root span could + represent a server receiving an initial client request. A root span could + also represent a scheduled job that has no remote context. + type: object + required: + - traceId + - id + properties: + traceId: + type: string + maxLength: 32 + minLength: 16 + pattern: "[a-z0-9]{16,32}" + description: | + Randomly generated, unique identifier for a trace, set on all spans within it. + + Encoded as 16 or 32 lowercase hex characters corresponding to 64 or 128 bits. + For example, a 128bit trace ID looks like 4e441824ec2b6a44ffdc9bb9a6453df3 + name: + type: string + description: | + The logical operation this span represents in lowercase (e.g. rpc method). + Leave absent if unknown. + + As these are lookup labels, take care to ensure names are low cardinality. + For example, do not embed variables into the name. + parentId: + type: string + pattern: "[a-z0-9]{16}" + maxLength: 16 + minLength: 16 + description: 'The parent span ID or absent if this the root span in a trace.' + id: + type: string + pattern: "[a-z0-9]{16}" + maxLength: 16 + minLength: 16 + description: | + Unique 64bit identifier for this operation within the trace. + + Encoded as 16 lowercase hex characters. For example ffdc9bb9a6453df3 + kind: + type: string + enum: + - CLIENT + - SERVER + - PRODUCER + - CONSUMER + description: | + When present, kind clarifies timestamp, duration and remoteEndpoint. When + absent, the span is local or incomplete. Unlike client and server, there + is no direct critical path latency relationship between producer and + consumer spans. + + * `CLIENT` + * timestamp is the moment a request was sent to the server. (in v1 "cs") + * duration is the delay until a response or an error was received. (in v1 "cr"-"cs") + * remoteEndpoint is the server. (in v1 "sa") + * `SERVER` + * timestamp is the moment a client request was received. (in v1 "sr") + * duration is the delay until a response was sent or an error. (in v1 "ss"-"sr") + * remote_endpoint is the client. (in v1 "ca") + * `PRODUCER` + * timestamp is the moment a message was sent to a destination. (in v1 "ms") + * duration is the delay sending the message, such as batching. + * remoteEndpoint is the broker. + * `CONSUMER` + * timestamp is the moment a message was received from an origin. (in v1 "mr") + * duration is the delay consuming the message, such as from backlog. + * remoteEndpoint - Represents the broker. Leave serviceName absent if unknown. + timestamp: + type: integer + format: int64 + description: | + Epoch microseconds of the start of this span, possibly absent if + incomplete. + + For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC + + This value should be set directly by instrumentation, using the most + precise value possible. For example, gettimeofday or multiplying epoch + millis by 1000. + + There are three known edge-cases where this could be reported absent. + * A span was allocated but never started (ex not yet received a timestamp) + * The span's start event was lost + * Data about a completed span (ex tags) were sent after the fact + duration: + type: integer + format: int64 + minimum: 1 + description: | + Duration in **microseconds** of the critical path, if known. Durations of less + than one are rounded up. Duration of children can be longer than their + parents due to asynchronous operations. + + For example 150 milliseconds is 150000 microseconds. + debug: + type: boolean + description: | + True is a request to store this span even if it overrides sampling policy. + + This is true when the `X-B3-Flags` header has a value of 1. + shared: + type: boolean + description: 'True if we are contributing to a span started by another tracer (ex on a different host).' + localEndpoint: + $ref: "#/definitions/Endpoint" + description: | + The host that recorded this span, primarily for query by service name. + + Instrumentation should always record this. Usually, absent implies late + data. The IP address corresponding to this is usually the site local or + advertised service address. When present, the port indicates the listen + port. + remoteEndpoint: + $ref: "#/definitions/Endpoint" + description: | + When an RPC (or messaging) span, indicates the other side of the + connection. + + By recording the remote endpoint, your trace will contain network context + even if the peer is not tracing. For example, you can record the IP from + the `X-Forwarded-For` header or the service name and socket of a remote + peer. + annotations: + type: array + uniqueItems: true + items: + $ref: '#/definitions/Annotation' + description: 'Associates events that explain latency with the time they happened.' + tags: + $ref: '#/definitions/Tags' + description: 'Tags give your span context for search, viewing and analysis.' + DependencyLink: + title: DependencyLink + description: | + The count of traced calls between services, or between a service and a broker. + + The direction of the link is parent to child, and can be one of: + * client to server + * producer to broker + * broker to consumer + + Note: This is related to span ID count between a sender and receiver, but there + is nuance that makes it more difficult than counting unique span IDs. Ex. the + parent or child might be uninstrumented: detected via the remote endpoint. There + can also be scenarios where both sides are instrumented. Please use existing tools + such as zipkin-dependencies to derive links as they avoid under or over counting. + type: object + required: + - parent + - child + - callCount + properties: + parent: + type: string + description: 'The service name of the caller: client or message producer or broker.' + child: + type: string + description: 'The service name of the callee: server or message consumer or broker.' + callCount: + type: integer + description: 'Total traced calls made from the parent to the child.' + errorCount: + type: integer + description: 'Total traced calls made from the parent to the child known to be in error.'
