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/06/05 10:03:30 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 b24bbd4b6bca1ee97c946d08ed3ea73e333c4a0f
Author: jenkins <bu...@apache.org>
AuthorDate: Wed Jun 5 10:03:22 2019 +0000
force adds zipkin-api
---
zipkin-api/zipkin-api.yaml | 441 ++++++++++++++++++++++++++++++++++++
zipkin-api/zipkin2-api.yaml | 536 ++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 977 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/zipkin2-api.yaml b/zipkin-api/zipkin2-api.yaml
new file mode 100644
index 0000000..f439a53
--- /dev/null
+++ b/zipkin-api/zipkin2-api.yaml
@@ -0,0 +1,536 @@
+#
+# 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: "2"
+ 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: OK
+ 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:
+ $ref: "#/definitions/ListOfSpans"
+ '400':
+ description: Bad Request Error
+ post:
+ summary: |
+ Uploads a list of spans encoded per content-type, for example json.
+ consumes:
+ - application/json
+ - application/x-protobuf
+ parameters:
+ - in: body
+ name: spans
+ 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")
+ * remoteEndpoint 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.'
+ example:
+ id: "352bff9a74ca9ad2"
+ traceId: "5af7183fb1d4cf5f"
+ parentId: "6b221d5bc9e6496c"
+ name: "get /api"
+ timestamp: 1556604172355737
+ duration: 1431
+ kind: "SERVER"
+ localEndpoint:
+ serviceName: "backend"
+ ipv4: "192.168.99.1"
+ port: 3306
+ remoteEndpoint:
+ ipv4: "172.19.0.2"
+ port: 58648
+ tags:
+ http.method: "GET"
+ http.path: "/api"
+ 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.'