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