Skip to content

Commit cda9378

Browse files
author
Adrian Cole
committed
Adds openapi spec for POST /api/v2/spans including the json format
1 parent e1e9437 commit cda9378

File tree

3 files changed

+242
-18
lines changed

3 files changed

+242
-18
lines changed

‎README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,5 @@
44

55
This repo only includes the [OpenAPI Spec](./zipkin-api.yaml) of the API for now.
66

7-
* /api/v1 - Published [here](http://zipkin.io/zipkin-api/#/)
7+
* [/api/v1](./zipkin-api.yaml) - Still supported on zipkin-server
8+
* [/api/v2](./zipkin2-api.yaml) - Most recent and published [here](http://zipkin.io/zipkin-api/#/)

‎validate.js‎

Lines changed: 21 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,25 +3,29 @@
33
const Sway = require('sway');
44
const read = require('fs').readFileSync;
55
const load = require('js-yaml').load;
6-
const zipkinAPI = read('./zipkin-api.yaml').toString();
6+
const yamls = ['./zipkin-api.yaml', './zipkin2-api.yaml'];
77

8-
Sway.create({definition: load(zipkinAPI)}).then(api => {
9-
const result = api.validate();
8+
yamls.forEach(yaml => {
9+
const zipkinAPI = read(yaml).toString();
1010

11-
if (result.errors.length) {
12-
console.error('Validation failed.')
13-
console.error(JSON.stringify(result.errors));
14-
return;
15-
}
11+
Sway.create({definition: load(zipkinAPI)}).then(api => {
12+
const result = api.validate();
1613

17-
if (result.warnings.length) {
18-
console.warn('Warnings:')
19-
console.warn(JSON.stringify(result.warnings));
20-
}
14+
if (result.errors.length) {
15+
console.error(`Validation failed for ${yaml}`)
16+
console.error(JSON.stringify(result.errors));
17+
return;
18+
}
2119

22-
console.log('Validation passed');
23-
})
24-
.catch(error=> {
25-
console.error('Error loading API');
26-
console.error(error);
20+
if (result.warnings.length) {
21+
console.warn(`Warnings in ${yaml}:`)
22+
console.warn(JSON.stringify(result.warnings));
23+
}
24+
25+
console.log(`Validation of ${yaml} passed`);
26+
})
27+
.catch(error=> {
28+
console.error(`Error loading ${yaml}`);
29+
console.error(error);
30+
});
2731
});

‎zipkin2-api.yaml‎

Lines changed: 219 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,219 @@
1+
swagger: "2.0"
2+
info:
3+
version: "1.0.0"
4+
title: Zipkin API
5+
description: |
6+
Zipkin's v2 api currently includes a POST endpoint that can receive spans.
7+
host: localhost:9411
8+
basePath: /api/v2
9+
schemes:
10+
- http
11+
- https
12+
consumes:
13+
- application/json
14+
paths:
15+
/spans:
16+
post:
17+
description: |
18+
Uploads a list of spans encoded per content-type, for example json.
19+
consumes:
20+
- application/json
21+
produces: []
22+
parameters:
23+
- name: spans
24+
in: body
25+
description: A list of spans that belong to any trace.
26+
required: true
27+
schema:
28+
$ref: "#/definitions/ListOfSpans"
29+
responses:
30+
202:
31+
description: Accepted
32+
definitions:
33+
Endpoint:
34+
type: object
35+
title: Endpoint
36+
description: The network context of a node in the service graph
37+
properties:
38+
serviceName:
39+
type: string
40+
description: |
41+
Lower-case label of this node in the service graph, such as "favstar". Leave
42+
absent if unknown.
43+
44+
This is a primary label for trace lookup and aggregation, so it should be
45+
intuitive and consistent. Many use a name from service discovery.
46+
ipv4:
47+
type: string
48+
description: |
49+
The text representation of the primary IPv4 address associated with this
50+
a connection. Ex. 192.168.99.100 Absent if unknown.
51+
ipv6:
52+
type: string
53+
description: |
54+
The text representation of the primary IPv6 address associated with this
55+
a connection. Ex. 2001:db8::c001 Absent if unknown.
56+
57+
Prefer using the ipv4 field for mapped addresses.
58+
port:
59+
type: integer
60+
description: |
61+
Depending on context, this could be a listen port or the client-side of a
62+
socket. Absent if unknown
63+
Annotation:
64+
title: Annotation
65+
type: object
66+
description: |
67+
Associates an event that explains latency with a timestamp.
68+
Unlike log statements, annotations are often codes. Ex. "ws" for WireSend
69+
70+
Zipkin v1 core annotations such as "cs" and "sr" have been replaced with
71+
Span.Kind, which interprets timestamp and duration.
72+
properties:
73+
timestamp:
74+
type: integer
75+
description: |
76+
Epoch **microseconds** of this event.
77+
78+
For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC
79+
80+
This value should be set directly by instrumentation, using the most precise
81+
value possible. For example, gettimeofday or multiplying epoch millis by 1000.
82+
value:
83+
type: string
84+
description: |
85+
Usually a short tag indicating an event, like "error"
86+
87+
While possible to add larger data, such as garbage collection details, low
88+
cardinality event names both keep the size of spans down and also are easy
89+
to search against.
90+
Tags:
91+
type: object
92+
title: Tags
93+
description: |
94+
Adds context to a span, for search, viewing and analysis.
95+
96+
For example, a key "your_app.version" would let you lookup traces by version.
97+
A tag "sql.query" isn't searchable, but it can help in debugging when viewing
98+
a trace.
99+
additionalProperties:
100+
type: string
101+
ListOfSpans:
102+
title: ListOfSpans
103+
description: 'A list of spans with possibly different trace ids, in no particular order'
104+
type: array
105+
items:
106+
$ref: "#/definitions/Span"
107+
Span:
108+
title: Span
109+
type: object
110+
properties:
111+
traceId:
112+
type: string
113+
maxLength: 32
114+
minLength: 16
115+
description: |
116+
Randomly generated, unique identifier for a trace, set on all spans within it.
117+
118+
Encoded as 16 or 32 lowercase hex characters corresponding to 64 or 128 bits.
119+
For example, a 128bit trace ID looks like 4e441824ec2b6a44ffdc9bb9a6453df3
120+
name:
121+
type: string
122+
description: |
123+
The logical operation this span represents in lowercase (e.g. rpc method).
124+
Leave absent if unknown.
125+
126+
As these are lookup labels, take care to ensure names are low cardinality.
127+
For example, do not embed variables into the name.
128+
parentId:
129+
type: string
130+
maxLength: 16
131+
minLength: 16
132+
description: 'The parent span ID or absent if this the root span in a trace.'
133+
id:
134+
type: string
135+
maxLength: 16
136+
minLength: 16
137+
description: |
138+
Unique 64bit identifier for this operation within the trace.
139+
140+
Encoded as 16 lowercase hex characters. For example ffdc9bb9a6453df3
141+
kind:
142+
type: string
143+
enum:
144+
- CLIENT
145+
- SERVER
146+
- PRODUCER
147+
- CONSUMER
148+
description: |
149+
When present, clarifies timestamp, duration and remoteEndpoint. When
150+
absent, the span is local or incomplete.
151+
152+
* `CLIENT`
153+
* timestamp - The moment a request was sent (formerly "cs")
154+
* duration - When present indicates when a response was received (formerly "cr")
155+
* remoteEndpoint - Represents the server. Leave serviceName absent if unknown.
156+
* `SERVER`
157+
* timestamp - The moment a request was received (formerly "sr")
158+
* duration - When present indicates when a response was sent (formerly "ss")
159+
* remoteEndpoint - Represents the client. Leave serviceName absent if unknown.
160+
* `PRODUCER`
161+
* timestamp - The moment a message was sent to a destination (formerly "ms")
162+
* duration - When present represents delay sending the message, such as batching.
163+
* remoteEndpoint - Represents the broker. Leave serviceName absent if unknown.
164+
* `CONSUMER`
165+
* timestamp - The moment a message was received from an origin (formerly "mr")
166+
* duration - When present represents delay consuming the message, such as from backlog.
167+
* remoteEndpoint - Represents the broker. Leave serviceName absent if unknown.
168+
timestamp:
169+
type: integer
170+
format: int64
171+
description: |
172+
Epoch **microseconds** of the start of this span, possibly absent if incomplete.
173+
174+
For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC
175+
176+
This value should be set directly by instrumentation, using the most precise
177+
value possible. For example, gettimeofday or multiplying epoch millis by 1000.
178+
179+
There are three known edge-cases where this could be reported absent.
180+
* A span was allocated but never started (ex not yet received a timestamp)
181+
* The span's start event was lost
182+
* Data about a completed span (ex tags) were sent after the fact
183+
duration:
184+
type: integer
185+
format: int64
186+
description: |
187+
Duration in **microseconds** of the critical path, if known. Durations of less
188+
than one are rounded up.
189+
190+
For example 150 milliseconds is 150000 microseconds.
191+
debug:
192+
type: boolean
193+
description: |
194+
True is a request to store this span even if it overrides sampling policy.
195+
196+
This is true when the `X-B3-Flags` header has a value of 1.
197+
shared:
198+
type: boolean
199+
description: 'True if we are contributing to a span started by another tracer (ex on a different host).'
200+
localEndpoint:
201+
$ref: "#/definitions/Endpoint"
202+
description: |
203+
The host that recorded this span, primarily for query by service name.
204+
205+
Instrumentation should always record this. Usually, absent implies late data.
206+
The IP address corresponding to this is usually the site local or advertised
207+
service address. When present, the port indicates the listen port.
208+
remoteEndpoint:
209+
$ref: "#/definitions/Endpoint"
210+
description: |
211+
When an RPC (or messaging) span, indicates the other side of the connection.
212+
annotations:
213+
type: array
214+
items:
215+
$ref: '#/definitions/Annotation'
216+
description: 'Associates events that explain latency with the time they happened.'
217+
tags:
218+
$ref: '#/definitions/Tags'
219+
description: 'Tags give your span context for search, viewing and analysis.'

0 commit comments

Comments
 (0)