Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API doc improvements #51

Merged
merged 3 commits into from
Apr 30, 2019
Merged

API doc improvements #51

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ae050e2
API doc improvements
cshoe May 2, 2018
db65e8f
Merge branch 'master' into 46-fix-sample-json
adriancole Apr 30, 2019
a8c255f
changed server to a real example
adriancole Apr 30, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 49 additions & 34 deletions zipkin2-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -337,19 +334,19 @@ definitions:
title: ListOfTraces
type: array
items:
$ref: "#/definitions/Trace"
$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
Expand All @@ -367,15 +364,15 @@ 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:
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:
Expand All @@ -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
Expand All @@ -405,15 +402,15 @@ 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")
* 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")
* 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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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: |
Expand Down