+++ /dev/null
-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
\ No newline at end of file
projects / ceph.git / blobdiff