This is an automated email from the ASF dual-hosted git repository.
adriancole pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-zipkin-api.git
The following commit(s) were added to refs/heads/master by this push:
new 6a76bc0 API doc improvements (#51)
6a76bc0 is described below
commit 6a76bc0236abc7ffa073ecb4ce95d825e8dfddb6
Author: Chris Schomaker <[email protected]>
AuthorDate: Mon Apr 29 23:07:24 2019 -0700
API doc improvements (#51)
* API doc improvements
* changed version to 2
* Added example values for span. This makes the example JSON in the
spans POST valid.
---
zipkin2-api.yaml | 83 +++++++++++++++++++++++++++++++++-----------------------
1 file changed, 49 insertions(+), 34 deletions(-)
diff --git a/zipkin2-api.yaml b/zipkin2-api.yaml
index 9d25da7..f439a53 100644
--- a/zipkin2-api.yaml
+++ b/zipkin2-api.yaml
@@ -17,7 +17,7 @@
swagger: "2.0"
info:
- version: "1.0.0"
+ version: "2"
title: Zipkin API
description: |
Zipkin's v2 api currently includes a POST endpoint that can receive spans.
@@ -35,7 +35,7 @@ paths:
Returns a list of all service names associated with span endpoints.
responses:
'200':
- description: Succes
+ description: OK
schema:
type: array
items:
@@ -57,21 +57,18 @@ paths:
'200':
description: OK
schema:
- type: array
- items:
- type: string
+ $ref: "#/definitions/ListOfSpans"
'400':
- description: Bad Request Error
+ description: Bad Request Error
post:
- description: |
- Uploads a list of spans encoded per content-type, for example json.
+ summary: |
+ Uploads a list of spans encoded per content-type, for example json.
consumes:
- application/json
- application/x-protobuf
- produces: []
parameters:
- - name: spans
- in: body
+ - in: body
+ name: spans
description: A list of spans that belong to any trace.
required: true
schema:
@@ -168,7 +165,7 @@ paths:
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:
@@ -258,7 +255,7 @@ definitions:
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:
@@ -273,7 +270,7 @@ definitions:
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
@@ -286,7 +283,7 @@ definitions:
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:
@@ -297,16 +294,16 @@ definitions:
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.
@@ -315,7 +312,7 @@ definitions:
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.
@@ -337,7 +334,7 @@ definitions:
title: ListOfTraces
type: array
items:
- $ref: "#/definitions/Trace"
+ $ref: "#/definitions/Trace"
Span:
title: Span
description: |
@@ -345,11 +342,11 @@ definitions:
(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
@@ -367,7 +364,7 @@ definitions:
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:
@@ -375,7 +372,7 @@ definitions:
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:
@@ -391,7 +388,7 @@ definitions:
minLength: 16
description: |
Unique 64bit identifier for this operation within the
trace.
-
+
Encoded as 16 lowercase hex characters. For example
ffdc9bb9a6453df3
kind:
type: string
@@ -405,7 +402,7 @@ definitions:
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")
@@ -413,7 +410,7 @@ definitions:
* `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")
+ * 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.
@@ -428,13 +425,13 @@ definitions:
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
@@ -447,13 +444,13 @@ definitions:
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
@@ -462,7 +459,7 @@ definitions:
$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
@@ -472,7 +469,7 @@ definitions:
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
@@ -486,6 +483,24 @@ definitions:
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: |
