From ae050e2489e14c22bc96dce9f7a86ac8f3f5ac33 Mon Sep 17 00:00:00 2001 From: Chris Schomaker Date: Wed, 2 May 2018 12:05:23 -0700 Subject: [PATCH 1/2] API doc improvements * changed version to 2 * Added example values for span. This makes the example JSON in the spans POST valid. (Fixes #46). The spans POST documentation is still a bit misleading. With the parameter named "spans", it seems to imply that it's expecting ```json { "spans": [{<...span...>}, {<....span...>}] } ``` but it actually just wants: ```json [{<...span...>}, {<...span...>}] ``` I couldn't figure out a way to acurately represent this in Swagger 2. It might be possible using [Swagger 3 request body descriptions.](https://swagger.io/docs/specification/describing-request-body/) --- zipkin2-api.yaml | 83 ++++++++++++++++++++++++++++-------------------- 1 file changed, 49 insertions(+), 34 deletions(-) diff --git a/zipkin2-api.yaml b/zipkin2-api.yaml index eca18eb..80884c9 100644 --- a/zipkin2-api.yaml +++ b/zipkin2-api.yaml @@ -1,6 +1,6 @@ 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. @@ -18,7 +18,7 @@ paths: Returns a list of all service names associated with span endpoints. responses: '200': - description: Succes + description: OK schema: type: array items: @@ -40,20 +40,17 @@ 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 - produces: [] parameters: - - name: spans - in: body + - in: body + name: spans description: A list of spans that belong to any trace. required: true schema: @@ -150,7 +147,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: @@ -200,7 +197,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: @@ -215,7 +212,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 @@ -228,7 +225,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. properties: @@ -236,16 +233,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. @@ -254,7 +251,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,7 +273,7 @@ definitions: title: ListOfTraces type: array items: - $ref: "#/definitions/Trace" + $ref: "#/definitions/Trace" Span: title: Span description: | @@ -284,11 +281,11 @@ definitions: (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 @@ -306,7 +303,7 @@ 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: @@ -314,7 +311,7 @@ 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: @@ -330,7 +327,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 @@ -344,7 +341,7 @@ 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") @@ -352,7 +349,7 @@ definitions: * `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. @@ -367,13 +364,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 @@ -386,13 +383,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 @@ -401,7 +398,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 @@ -411,7 +408,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 @@ -425,6 +422,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: "query" + timestamp: 1461750040359000 + duration: 5000 + kind: "SERVER" + localEndpoint: + serviceName: "mysql" + ipv4: "172.19.0.2" + port: 3306 + remoteEndpoint: + serviceName: "mysql" + ipv4: "172.19.0.2" + port: 3306 + tags: + jdbc.query: "select distinct `zipkin_spans`.`trace_id` from `zipkin_spans`" DependencyLink: title: DependencyLink type: object From a8c255fab3e24bba4100145e0d4f891734275d98 Mon Sep 17 00:00:00 2001 From: Adrian Cole Date: Tue, 30 Apr 2019 14:05:05 +0800 Subject: [PATCH 2/2] changed server to a real example --- zipkin2-api.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/zipkin2-api.yaml b/zipkin2-api.yaml index b1b7932..f439a53 100644 --- a/zipkin2-api.yaml +++ b/zipkin2-api.yaml @@ -487,20 +487,20 @@ definitions: id: "352bff9a74ca9ad2" traceId: "5af7183fb1d4cf5f" parentId: "6b221d5bc9e6496c" - name: "query" - timestamp: 1461750040359000 - duration: 5000 + name: "get /api" + timestamp: 1556604172355737 + duration: 1431 kind: "SERVER" localEndpoint: - serviceName: "mysql" - ipv4: "172.19.0.2" + serviceName: "backend" + ipv4: "192.168.99.1" port: 3306 remoteEndpoint: - serviceName: "mysql" ipv4: "172.19.0.2" - port: 3306 + port: 58648 tags: - jdbc.query: "select distinct `zipkin_spans`.`trace_id` from `zipkin_spans`" + http.method: "GET" + http.path: "/api" DependencyLink: title: DependencyLink description: |