diff --git a/Makefile b/Makefile index f3a23a7..da10c03 100644 --- a/Makefile +++ b/Makefile @@ -3,7 +3,7 @@ THRIFT_VER?=0.13 THRIFT_IMG?=jaegertracing/thrift:$(THRIFT_VER) THRIFT=docker run --rm -u $(shell id -u) -v "${PWD}:/data" $(THRIFT_IMG) thrift -SWAGGER_VER=0.12.0 +SWAGGER_VER=0.31.0 SWAGGER_IMAGE=quay.io/goswagger/swagger:$(SWAGGER_VER) SWAGGER=docker run --rm -u ${shell id -u} -v "${PWD}:/go/src/${PROJECT_ROOT}" -w /go/src/${PROJECT_ROOT} $(SWAGGER_IMAGE) diff --git a/swagger/zipkin2-api.yaml b/swagger/zipkin2-api.yaml index f97c3f1..7c7f183 100644 --- a/swagger/zipkin2-api.yaml +++ b/swagger/zipkin2-api.yaml @@ -1,9 +1,23 @@ +# Copyright 2018-2024 The OpenZipkin Authors +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except +# in compliance with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software distributed under the License +# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express +# or implied. See the License for the specific language governing permissions and limitations under +# the License. +# +# Source: https://zipkin.io/zipkin-api/zipkin2-api.yaml + 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. + Zipkin's v2 API currently includes a POST endpoint that can receive spans. host: localhost:9411 basePath: /api/v2 schemes: @@ -17,13 +31,13 @@ paths: description: | Returns a list of all service names associated with span endpoints. responses: - 200: - description: Succes + '200': + description: OK schema: type: array items: type: string - 400: + '400': description: Bad Request Error /spans: get: @@ -37,29 +51,27 @@ paths: graph. The /services endpoint enumerates possible input values. type: string responses: - 200: + '200': description: OK schema: - type: array - items: - type: string - 400: - description: Bad Request Error + $ref: "#/definitions/ListOfSpans" + '400': + 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 - produces: [] + - application/x-protobuf parameters: - - name: spans - in: body + - in: body + name: spans description: A list of spans that belong to any trace. required: true schema: $ref: "#/definitions/ListOfSpans" responses: - 202: + '202': description: Accepted /traces: get: @@ -103,12 +115,14 @@ paths: - name: minDuration in: query type: integer + format: int64 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 + format: int64 description: | Only return traces whose Span.duration is less than or equal to `maxDuration` microseconds. Only valid with minDuration. @@ -134,7 +148,7 @@ paths: description: | Maximum number of traces to return. Defaults to 10 responses: - 200: + '200': description: OK schema: $ref: "#/definitions/ListOfTraces" @@ -147,19 +161,47 @@ paths: type: string maxLength: 32 minLength: 16 - pattern: "[a-z0-9]{16,32}" + pattern: "[a-f0-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: + '200': description: OK schema: $ref: "#/definitions/Trace" - 404: + '404': description: "`traceId` not found" + /traceMany: + get: + description: | + Invoking this request retrieves any traces with the specified IDs. + + Results return in any order, and can be empty. + + Use /trace/{traceId} to request a single trace ID: <2 trace IDs is a + bad request. + parameters: + - name: traceIds + in: query + type: string + minLength: 33 + pattern: "([a-f0-9]{16,32},)+([a-f0-9]{16,32})" + required: true + description: | + Comma delimited list of at least two unique trace identifiers. + + 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. List of traces that match the input traceIds, empty if none match. + schema: + $ref: "#/definitions/ListOfTraces" + '400': + description: Bad request. Less than two traceIds, or the list was redundant or malformed. /dependencies: get: description: | @@ -182,13 +224,53 @@ paths: type: integer format: int64 responses: - 200: + '200': description: OK schema: type: array title: ListOfDependencyLinks items: $ref: "#/definitions/DependencyLink" + /autocompleteKeys: + get: + description: | + Returns a subset of keys from Span.tags configured for value autocompletion. + This helps sites populate common keys into the annotationQuery parameter of the + /traces endpoint. For example, a UI can allow users to select site-specific + keys from a drop-down as opposed to typing them in manually. This helps guide + users towards the more correct keys and avoids typos or formatting problems. + responses: + '200': + description: Success is a list of site-specific keys, such as environment. + schema: + type: array + items: + type: string + '400': + description: Bad Request Error + /autocompleteValues: + get: + description: | + Returns all known values of Span.tags for the given autocomplete key. Refer + to the description of /autocompleteKeys for the use case. + parameters: + - name: key + in: query + required: true + description: Name of the autocomplete key from the /autocompleteKeys endpoint. + type: string + responses: + '200': + description: | + Success result is empty when there are no values or the key was not + configured. + schema: + type: array + items: + type: string + '400': + description: Bad Request Error + definitions: Endpoint: type: object @@ -200,7 +282,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: @@ -208,44 +290,48 @@ definitions: format: ipv4 description: | The text representation of the primary IPv4 address associated with this - a connection. Ex. 192.168.99.100 Absent if unknown. + 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. - + 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 description: | Depending on context, this could be a listen port or the client-side of a - socket. Absent if unknown + socket. Absent if unknown. Please don't set to zero. 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. + required: + - timestamp + - value properties: timestamp: type: integer + format: int64 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. @@ -254,7 +340,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. @@ -276,9 +362,24 @@ 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 + represent a server receiving an initial client request. A root span could + also represent a scheduled job that has no remote context. type: object required: - traceId @@ -288,10 +389,10 @@ definitions: type: string maxLength: 32 minLength: 16 - pattern: "[a-z0-9]{16,32}" + pattern: "[a-f0-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: @@ -299,23 +400,23 @@ 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: type: string - pattern: "[a-z0-9]{16}" + pattern: "[a-f0-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}" + pattern: "[a-f0-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 @@ -325,38 +426,40 @@ definitions: - 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. - + When present, kind 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. + * 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 - 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. + * 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") + * remoteEndpoint is the client. (in v1 "ca") * `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. + * timestamp is the moment a message was sent to a destination. (in v1 "ms") + * duration is the delay sending the message, such as batching. + * remoteEndpoint is the broker. * `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. + * timestamp is the moment a message was received from an origin. (in v1 "mr") + * duration is the 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. - + 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. - + + 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 @@ -367,15 +470,15 @@ definitions: 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. - + 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 @@ -384,14 +487,21 @@ 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 port. + + 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. + 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 + peer. annotations: type: array uniqueItems: true @@ -401,15 +511,54 @@ 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: | + The count of traced calls between services, or between a service and a broker. + + The direction of the link is parent to child, and can be one of: + * client to server + * producer to broker + * broker to consumer + + Note: This is related to span ID count between a sender and receiver, but there + is nuance that makes it more difficult than counting unique span IDs. Ex. the + parent or child might be uninstrumented: detected via the remote endpoint. There + can also be scenarios where both sides are instrumented. Please use existing tools + such as zipkin-dependencies to derive links as they avoid under or over counting. type: object + required: + - parent + - child + - callCount properties: parent: type: string + description: 'The service name of the caller: client or message producer or broker.' child: type: string + description: 'The service name of the callee: server or message consumer or broker.' callCount: type: integer + description: 'Total traced calls made from the parent to the child.' errorCount: - type: integer \ No newline at end of file + type: integer + description: 'Total traced calls made from the parent to the child known to be in error.'