[ceph.git] / ceph / src / jaegertracing / jaeger-client-cpp / idl / swagger / zipkin2-api.yaml

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
      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"
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
                    a 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 this
                    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
  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.
    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
    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, 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 - The moment a request was sent (formerly "cs")
                      * duration - When present indicates when a response was received (formerly "cr")
                      * remoteEndpoint - Represents the server. Leave serviceName absent if unknown.
                    * `SERVER`
                      * timestamp - The moment a request was received (formerly "sr")
                      * duration - When present indicates when a response was sent (formerly "ss")
                      * remoteEndpoint - Represents the client. Leave serviceName absent if unknown.
                    * `PRODUCER`
                      * timestamp - The moment a message was sent to a destination (formerly "ms")
                      * duration - When present represents delay sending the message, such as batching.
                      * remoteEndpoint - Represents the broker. Leave serviceName absent if unknown.
                    * `CONSUMER`
                      * timestamp - The moment a message was received from an origin (formerly "mr")
                      * duration - When present represents 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.
      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
    type: object
    properties:
      parent:
        type: string
      child:
        type: string
      callCount:
        type: integer
      errorCount:
        type: integer
Commit	Line	Data
f67539c2 TL	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	/services:
	16	get:
	17	description: \|
	18	Returns a list of all service names associated with span endpoints.
	19	responses:
	20	200:
	21	description: Succes
	22	schema:
	23	type: array
	24	items:
	25	type: string
	26	400:
	27	description: Bad Request Error
	28	/spans:
	29	get:
	30	description: Get all the span names recorded by a particular service
	31	parameters:
	32	- name: serviceName
	33	in: query
	34	required: true
	35	description: \|
	36	Ex favstar (required) - Lower-case label of a node in the service
	37	graph. The /services endpoint enumerates possible input values.
	38	type: string
	39	responses:
	40	200:
	41	description: OK
	42	schema:
	43	type: array
	44	items:
	45	type: string
	46	400:
	47	description: Bad Request Error
	48	post:
	49	description: \|
	50	Uploads a list of spans encoded per content-type, for example json.
	51	consumes:
	52	- application/json
	53	produces: []
	54	parameters:
	55	- name: spans
	56	in: body
	57	description: A list of spans that belong to any trace.
	58	required: true
	59	schema:
	60	$ref: "#/definitions/ListOfSpans"
	61	responses:
	62	202:
	63	description: Accepted
	64	/traces:
65	get:
66	description: \|
67	Invoking this request retrieves traces matching the below filters.
68
69	Results should be filtered against endTs, subject to limit and
70	lookback. For example, if endTs is 10:20 today, limit is 10, and
71	lookback is 7 days, traces returned should be those nearest to 10:20
72	today, not 10:20 a week ago.
73
74	Time units of endTs and lookback are milliseconds as opposed to
75	microseconds, the grain of Span.timestamp. Milliseconds is a more
76	familiar and supported granularity for query, index and windowing
77	functions
78	parameters:
79	- name: serviceName
80	in: query
81	required: false
82	description: \|
83	Ex favstar (required) - Lower-case label of a node in the service
84	graph. The /services endpoint enumerates possible input values.
85	type: string
86	- name: spanName
87	in: query
88	required: false
89	description: \|
90	Ex get - name of a span in a trace.
91	Only return traces that contains spans with this name.
92	type: string
93	- name: annotationQuery
94	in: query
95	type: string
96	required: false
97	description: \|
98	Ex. `http.uri=/foo and retried` - If key/value (has an `=`),
99	constrains against Span.tags entres. If just a word, constrains
100	against Span.annotations[].value or Span.tags[].key. Any values are
101	AND against eachother. This means a span in the trace must match
102	all of these.
103	- name: minDuration
104	in: query
105	type: integer
106	description: \|
107	Ex. 100000 (for 100ms). Only return traces whose `Span.duration` is
108	greater than or equal to minDuration microseconds.
109	- name: maxDuration
110	in: query
111	type: integer
112	description: \|
113	Only return traces whose Span.duration is less than or equal to
114	`maxDuration` microseconds. Only valid with minDuration.
115	- name: endTs
116	in: query
117	type: integer
118	format: int64
119	description: \|
120	Only return traces where all Span.timestamp are at or before this
121	time in epoch milliseconds. Defaults to current time.
122	- name: lookback
123	type: integer
124	format: int64
125	in: query
126	description: \|
127	Only return traces where all Span.timestamp are at or after (endTs
128	- * lookback) in milliseconds. Defaults to endTs, limited to a
129	system parameter QUERY_LOOKBACK
130	- name: limit
131	in: query
132	default: 10
133	type: integer
134	description: \|
135	Maximum number of traces to return. Defaults to 10
136	responses:
137	200:
138	description: OK
139	schema:
140	$ref: "#/definitions/ListOfTraces"
141	/trace/{traceId}:
142	get:
143	parameters:
144	- name: traceId
145	in: path
146	required: true
147	type: string
148	maxLength: 32
149	minLength: 16
150	pattern: "[a-z0-9]{16,32}"
151	description: \|
152	Trace identifier, set on all spans within it.
153
154	Encoded as 16 or 32 lowercase hex characters corresponding to 64 or 128 bits.
155	For example, a 128bit trace ID looks like 4e441824ec2b6a44ffdc9bb9a6453df3
156	responses:
157	200:
158	description: OK
159	schema:
160	$ref: "#/definitions/Trace"
161	404:
162	description: "`traceId` not found"
163	/dependencies:
164	get:
165	description: \|
166	Returns service links derived from spans.
167	parameters:
168	- name: endTs
169	in: query
170	description: \|
171	only return links from spans where `Span.timestamp` are at or before
172	this time in epoch milliseconds.
173	required: true
174	type: integer
175	format: int64
176	- name: lookback
177	in: query
178	description: \|
179	only return links where all Span.timestamp are at or after
180	(`endTs - * lookback`) in milliseconds. Defaults to `endTs`, limited
181	to a system parameter `QUERY_LOOKBACK`
182	type: integer
183	format: int64
184	responses:
185	200:
186	description: OK
187	schema:
188	type: array
189	title: ListOfDependencyLinks
190	items:
191	$ref: "#/definitions/DependencyLink"
192	definitions:
193	Endpoint:
194	type: object
195	title: Endpoint
196	description: The network context of a node in the service graph
197	properties:
198	serviceName:
199	type: string
200	description: \|
201	Lower-case label of this node in the service graph, such as "favstar". Leave
202	absent if unknown.
203
204	This is a primary label for trace lookup and aggregation, so it should be
205	intuitive and consistent. Many use a name from service discovery.
206	ipv4:
207	type: string
208	format: ipv4
209	description: \|
210	The text representation of the primary IPv4 address associated with this
211	a connection. Ex. 192.168.99.100 Absent if unknown.
212	ipv6:
213	type: string
214	format: ipv6
215	description: \|
216	The text representation of the primary IPv6 address associated with this
217	a connection. Ex. 2001:db8::c001 Absent if unknown.
218
219	Prefer using the ipv4 field for mapped addresses.
220	port:
221	type: integer
222	description: \|
223	Depending on context, this could be a listen port or the client-side of a
224	socket. Absent if unknown
225	Annotation:
226	title: Annotation
227	type: object
228	description: \|
229	Associates an event that explains latency with a timestamp.
230	Unlike log statements, annotations are often codes. Ex. "ws" for WireSend
231
232	Zipkin v1 core annotations such as "cs" and "sr" have been replaced with
233	Span.Kind, which interprets timestamp and duration.
234	properties:
235	timestamp:
236	type: integer
237	description: \|
238	Epoch microseconds of this event.
239
240	For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC
241
242	This value should be set directly by instrumentation, using the most precise
243	value possible. For example, gettimeofday or multiplying epoch millis by 1000.
244	value:
245	type: string
246	description: \|
247	Usually a short tag indicating an event, like "error"
248
249	While possible to add larger data, such as garbage collection details, low
250	cardinality event names both keep the size of spans down and also are easy
251	to search against.
252	Tags:
253	type: object
254	title: Tags
255	description: \|
256	Adds context to a span, for search, viewing and analysis.
257
258	For example, a key "your_app.version" would let you lookup traces by version.
259	A tag "sql.query" isn't searchable, but it can help in debugging when viewing
260	a trace.
261	additionalProperties:
262	type: string
263	ListOfSpans:
264	title: ListOfSpans
265	description: 'A list of spans with possibly different trace ids, in no particular order'
266	type: array
267	items:
268	$ref: "#/definitions/Span"
269	Trace:
270	title: Trace
271	type: array
272	description: 'List of spans who have the same trace ID.'
273	items:
274	$ref: "#/definitions/Span"
275	ListOfTraces:
276	title: ListOfTraces
277	type: array
278	items:
279	$ref: "#/definitions/Trace"
280	Span:
281	title: Span
282	type: object
283	required:
284	- traceId
285	- id
286	properties:
287	traceId:
288	type: string
289	maxLength: 32
290	minLength: 16
291	pattern: "[a-z0-9]{16,32}"
292	description: \|
293	Randomly generated, unique identifier for a trace, set on all spans within it.
294
295	Encoded as 16 or 32 lowercase hex characters corresponding to 64 or 128 bits.
296	For example, a 128bit trace ID looks like 4e441824ec2b6a44ffdc9bb9a6453df3
297	name:
298	type: string
299	description: \|
300	The logical operation this span represents in lowercase (e.g. rpc method).
301	Leave absent if unknown.
302
303	As these are lookup labels, take care to ensure names are low cardinality.
304	For example, do not embed variables into the name.
305	parentId:
306	type: string
307	pattern: "[a-z0-9]{16}"
308	maxLength: 16
309	minLength: 16
310	description: 'The parent span ID or absent if this the root span in a trace.'
311	id:
312	type: string
313	pattern: "[a-z0-9]{16}"
314	maxLength: 16
315	minLength: 16
316	description: \|
317	Unique 64bit identifier for this operation within the trace.
318
319	Encoded as 16 lowercase hex characters. For example ffdc9bb9a6453df3
320	kind:
321	type: string
322	enum:
323	- CLIENT
324	- SERVER
325	- PRODUCER
326	- CONSUMER
327	description: \|
328	When present, clarifies timestamp, duration and remoteEndpoint. When
329	absent, the span is local or incomplete. Unlike client and server,
330	there is no direct critical path latency relationship between producer
331	and consumer spans.
332
333	* `CLIENT`
334	* timestamp - The moment a request was sent (formerly "cs")
335	* duration - When present indicates when a response was received (formerly "cr")
336	* remoteEndpoint - Represents the server. Leave serviceName absent if unknown.
337	* `SERVER`
338	* timestamp - The moment a request was received (formerly "sr")
339	* duration - When present indicates when a response was sent (formerly "ss")
340	* remoteEndpoint - Represents the client. Leave serviceName absent if unknown.
341	* `PRODUCER`
342	* timestamp - The moment a message was sent to a destination (formerly "ms")
343	* duration - When present represents delay sending the message, such as batching.
344	* remoteEndpoint - Represents the broker. Leave serviceName absent if unknown.
345	* `CONSUMER`
346	* timestamp - The moment a message was received from an origin (formerly "mr")
347	* duration - When present represents delay consuming the message, such as from backlog.
348	* remoteEndpoint - Represents the broker. Leave serviceName absent if unknown.
349	timestamp:
350	type: integer
351	format: int64
352	description: \|
353	Epoch microseconds of the start of this span, possibly absent if incomplete.
354
355	For example, 1502787600000000 corresponds to 2017-08-15 09:00 UTC
356
357	This value should be set directly by instrumentation, using the most precise
358	value possible. For example, gettimeofday or multiplying epoch millis by 1000.
359
360	There are three known edge-cases where this could be reported absent.
361	* A span was allocated but never started (ex not yet received a timestamp)
362	* The span's start event was lost
363	* Data about a completed span (ex tags) were sent after the fact
364	duration:
365	type: integer
366	format: int64
367	minimum: 1
368	description: \|
369	Duration in microseconds of the critical path, if known. Durations of less
370	than one are rounded up. Duration of children can be longer than their parents
371	due to asynchronous operations.
372
373	For example 150 milliseconds is 150000 microseconds.
374	debug:
375	type: boolean
376	description: \|
377	True is a request to store this span even if it overrides sampling policy.
378
379	This is true when the `X-B3-Flags` header has a value of 1.
380	shared:
381	type: boolean
382	description: 'True if we are contributing to a span started by another tracer (ex on a different host).'
383	localEndpoint:
384	$ref: "#/definitions/Endpoint"
385	description: \|
386	The host that recorded this span, primarily for query by service name.
387
388	Instrumentation should always record this. Usually, absent implies late data.
389	The IP address corresponding to this is usually the site local or advertised
390	service address. When present, the port indicates the listen port.
391	remoteEndpoint:
392	$ref: "#/definitions/Endpoint"
393	description: \|
394	When an RPC (or messaging) span, indicates the other side of the connection.
395	annotations:
396	type: array
397	uniqueItems: true
398	items:
399	$ref: '#/definitions/Annotation'
400	description: 'Associates events that explain latency with the time they happened.'
401	tags:
402	$ref: '#/definitions/Tags'
403	description: 'Tags give your span context for search, viewing and analysis.'
404	DependencyLink:
405	title: DependencyLink
406	type: object
407	properties:
408	parent:
409	type: string
410	child:
411	type: string
412	callCount:
413	type: integer
414	errorCount:
415	type: integer