You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zipkin.apache.org by ab...@apache.org on 2019/05/10 14:06:07 UTC
[incubator-zipkin-website] 01/02: force adds zipkin-api
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 <bu...@apache.org>
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.'