diff options
Diffstat (limited to '')
| -rw-r--r-- | src/jaegertracing/jaeger-client-cpp/idl/swagger/zipkin2-api.yaml | 415 |
1 files changed, 415 insertions, 0 deletions
diff --git a/src/jaegertracing/jaeger-client-cpp/idl/swagger/zipkin2-api.yaml b/src/jaegertracing/jaeger-client-cpp/idl/swagger/zipkin2-api.yaml new file mode 100644 index 000000000..f97c3f15b --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/swagger/zipkin2-api.yaml @@ -0,0 +1,415 @@ +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 |