diff options
Diffstat (limited to 'src/jaegertracing/jaeger-client-cpp/idl')
16 files changed, 1514 insertions, 0 deletions
diff --git a/src/jaegertracing/jaeger-client-cpp/idl/.gitignore b/src/jaegertracing/jaeger-client-cpp/idl/.gitignore new file mode 100644 index 000000000..5eaf37d73 --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/.gitignore @@ -0,0 +1,6 @@ +.idea/ +gen-go/ +gen-java/ +gen-nodejs/ +gen-py.tornado/ +gen-cpp/ diff --git a/src/jaegertracing/jaeger-client-cpp/idl/.travis.yml b/src/jaegertracing/jaeger-client-cpp/idl/.travis.yml new file mode 100644 index 000000000..8418b117b --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/.travis.yml @@ -0,0 +1,10 @@ +sudo: required + +services: + - docker + +before_install: + - docker version + +script: + - make test-ci diff --git a/src/jaegertracing/jaeger-client-cpp/idl/CONTRIBUTING.md b/src/jaegertracing/jaeger-client-cpp/idl/CONTRIBUTING.md new file mode 100644 index 000000000..088e5f7a8 --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/CONTRIBUTING.md @@ -0,0 +1,117 @@ +# How to Contribute to Jaeger + +We'd love your help! + +Jaeger is [Apache 2.0 licensed](LICENSE) and accepts contributions via GitHub +pull requests. This document outlines some of the conventions on development +workflow, commit message formatting, contact points and other resources to make +it easier to get your contribution accepted. + +We gratefully welcome improvements to documentation as well as to code. + +# Certificate of Origin + +By contributing to this project you agree to the [Developer Certificate of +Origin](https://developercertificate.org/) (DCO). This document was created +by the Linux Kernel community and is a simple statement that you, as a +contributor, have the legal right to make the contribution. See the [DCO](DCO) +file for details. + +## Making A Change + +*Before making any significant changes, please [open an +issue](https://github.com/uber/jaeger/issues).* Discussing your proposed +changes ahead of time will make the contribution process smooth for everyone. + +Once we've discussed your changes and you've got your code ready, make sure +that tests are passing (`make test-ci`) and open your PR. Your +pull request is most likely to be accepted if: + +* It has a [good commit + message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). +* Each commit must be signed by the author ([see below](#sign-your-work)). + +## License + +By contributing your code, you agree to license your contribution under the terms +of the [Apache License](LICENSE). + +If you are adding a new file it should have a header like below. + +``` +# Copyright (c) 2017 The Jaeger 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. +``` + +## Sign your work + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below (from +[developercertificate.org](http://developercertificate.org/)): + +``` +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +then you just add a line to every git commit message: + + Signed-off-by: Joe Smith <joe@gmail.com> + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +You can add the sign off when creating the git commit via `git commit -s`. + +If you want this to be automatic you can set up some aliases: + +``` +git config --add alias.amend "commit -s --amend" +git config --add alias.c "commit -s" +``` diff --git a/src/jaegertracing/jaeger-client-cpp/idl/DCO b/src/jaegertracing/jaeger-client-cpp/idl/DCO new file mode 100644 index 000000000..068953d4b --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/DCO @@ -0,0 +1,37 @@ +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +660 York Street, Suite 102, +San Francisco, CA 94110 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + diff --git a/src/jaegertracing/jaeger-client-cpp/idl/LICENSE b/src/jaegertracing/jaeger-client-cpp/idl/LICENSE new file mode 100644 index 000000000..261eeb9e9 --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + 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. diff --git a/src/jaegertracing/jaeger-client-cpp/idl/Makefile b/src/jaegertracing/jaeger-client-cpp/idl/Makefile new file mode 100644 index 000000000..f267cdcbf --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/Makefile @@ -0,0 +1,39 @@ + +THRIFT_VER=0.9.2 +THRIFT_IMG=thrift:$(THRIFT_VER) +THRIFT=docker run -u $(shell id -u) -v "${PWD}:/data" $(THRIFT_IMG) thrift + +SWAGGER_VER=0.12.0 +SWAGGER_IMAGE=quay.io/goswagger/swagger:$(SWAGGER_VER) +SWAGGER=docker run --rm -it -u ${shell id -u} -v "${PWD}:/go/src/${PROJECT_ROOT}" -w /go/src/${PROJECT_ROOT} $(SWAGGER_IMAGE) + +THRIFT_GO_ARGS=thrift_import="github.com/apache/thrift/lib/go/thrift" +THRIFT_PY_ARGS=new_style,tornado +THRIFT_JAVA_ARGS=private-members +THRIFT_PHP_ARGS=psr4 + +THRIFT_GEN=--gen go:$(THRIFT_GO_ARGS) --gen py:$(THRIFT_PY_ARGS) --gen java:$(THRIFT_JAVA_ARGS) --gen js:node --gen cpp --gen php:$(THRIFT_PHP_ARGS) +THRIFT_CMD=$(THRIFT) -o /data $(THRIFT_GEN) + +THRIFT_FILES=agent.thrift jaeger.thrift sampling.thrift zipkincore.thrift crossdock/tracetest.thrift \ + baggage.thrift dependency.thrift aggregation_validator.thrift + +test-ci: thrift swagger-validate + +swagger-validate: + $(SWAGGER) validate ./swagger/zipkin2-api.yaml + +clean: + rm -rf gen-* || true + +thrift: thrift-image clean $(THRIFT_FILES) + +$(THRIFT_FILES): + @echo Compiling $@ + $(THRIFT_CMD) /data/thrift/$@ + +thrift-image: + docker pull $(THRIFT_IMG) + $(THRIFT) -version + +.PHONY: test-ci clean thrift thrift-image $(THRIFT_FILES) swagger-validate diff --git a/src/jaegertracing/jaeger-client-cpp/idl/README.md b/src/jaegertracing/jaeger-client-cpp/idl/README.md new file mode 100644 index 000000000..05344439a --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/README.md @@ -0,0 +1,15 @@ +# jaeger-idl [![Build Status][ci-img]][ci] + +A set of shared data model definitions used by Jaeger components. + +## Contributing + +See [CONTRIBUTING](./CONTRIBUTING.md). + +## License + +[Apache 2.0 License](./LICENSE). + + +[ci-img]: https://travis-ci.org/jaegertracing/jaeger-idl.svg?branch=master +[ci]: https://travis-ci.org/jaegertracing/jaeger-idl 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 diff --git a/src/jaegertracing/jaeger-client-cpp/idl/thrift/agent.thrift b/src/jaegertracing/jaeger-client-cpp/idl/thrift/agent.thrift new file mode 100644 index 000000000..b7c152bda --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/thrift/agent.thrift @@ -0,0 +1,26 @@ +# Copyright (c) 2016 Uber Technologies, Inc. +# +# 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. + +include "jaeger.thrift" +include "zipkincore.thrift" + +namespace cpp jaegertracing.agent.thrift +namespace java io.jaegertracing.agent.thrift +namespace php Jaeger.Thrift.Agent +namespace netcore Jaeger.Thrift.Agent + +service Agent { + oneway void emitZipkinBatch(1: list<zipkincore.Span> spans) + oneway void emitBatch(1: jaeger.Batch batch) +} diff --git a/src/jaegertracing/jaeger-client-cpp/idl/thrift/aggregation_validator.thrift b/src/jaegertracing/jaeger-client-cpp/idl/thrift/aggregation_validator.thrift new file mode 100644 index 000000000..733d97432 --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/thrift/aggregation_validator.thrift @@ -0,0 +1,28 @@ +# Copyright (c) 2017 Uber Technologies, Inc. +# +# 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. + +namespace cpp jaegertracing.thrift +namespace java io.jaegertracing.thriftjava +namespace php Jaeger.Thrift.Agent +namespace netcore Jaeger.Thrift.Agent + +# ValidateTraceResponse returns ok when a trace has been written to redis. +struct ValidateTraceResponse { + 1: required bool ok + 2: required i64 traceCount +} + +service AggregationValidator { + ValidateTraceResponse validateTrace(1: required string traceId) +} diff --git a/src/jaegertracing/jaeger-client-cpp/idl/thrift/baggage.thrift b/src/jaegertracing/jaeger-client-cpp/idl/thrift/baggage.thrift new file mode 100644 index 000000000..56a27a128 --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/thrift/baggage.thrift @@ -0,0 +1,33 @@ +# Copyright (c) 2017 Uber Technologies, Inc. +# +# 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. + +namespace cpp jaegertracing.thrift +namespace java io.jaegertracing.thriftjava +namespace php Jaeger.Thrift.Agent +namespace netcore Jaeger.Thrift.Agent + +# BaggageRestriction contains the baggage key and the maximum length of the baggage value. +struct BaggageRestriction { + 1: required string baggageKey + 2: required i32 maxValueLength +} + +service BaggageRestrictionManager { + /** + * getBaggageRestrictions retrieves the baggage restrictions for a specific service. + * Usually, baggageRestrictions apply to all services however there may be situations + * where a baggageKey might only be allowed to be set by a specific service. + */ + list<BaggageRestriction> getBaggageRestrictions(1: string serviceName) +} diff --git a/src/jaegertracing/jaeger-client-cpp/idl/thrift/crossdock/tracetest.thrift b/src/jaegertracing/jaeger-client-cpp/idl/thrift/crossdock/tracetest.thrift new file mode 100644 index 000000000..d923b1029 --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/thrift/crossdock/tracetest.thrift @@ -0,0 +1,64 @@ +# Copyright (c) 2016 Uber Technologies, Inc. +# +# 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. + +namespace cpp jaegertracing.crossdock.thrift +namespace java io.jaegertracing.crossdock.thrift +namespace php Jaeger.Thrift.Crossdock +namespace netcore Jaeger.Thrift.Crossdock + +enum Transport { HTTP, TCHANNEL, DUMMY } + +struct Downstream { + 1: required string serviceName + 2: required string serverRole + 3: required string host + 4: required string port + 5: required Transport transport + 6: optional Downstream downstream +} + +struct StartTraceRequest { + 1: required string serverRole // role of the server (always S1) + 2: required bool sampled + 3: required string baggage + 4: required Downstream downstream +} + +struct JoinTraceRequest { + 1: required string serverRole // role of the server, S2 or S3 + 2: optional Downstream downstream +} + +struct ObservedSpan { + 1: required string traceId + 2: required bool sampled + 3: required string baggage +} + +/** + * Each server must include the information about the span it observed. + * It can only be omitted from the response if notImplementedError field is not empty. + * If the server was instructed to make a downstream call, it must embed the + * downstream response in its own response. + */ +struct TraceResponse { + 1: optional ObservedSpan span + 2: optional TraceResponse downstream + 3: required string notImplementedError +} + +service TracedService { + TraceResponse startTrace(1: StartTraceRequest request) + TraceResponse joinTrace(1: JoinTraceRequest request) +} diff --git a/src/jaegertracing/jaeger-client-cpp/idl/thrift/dependency.thrift b/src/jaegertracing/jaeger-client-cpp/idl/thrift/dependency.thrift new file mode 100644 index 000000000..781e1c4a5 --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/thrift/dependency.thrift @@ -0,0 +1,37 @@ +# Copyright (c) 2017 Uber Technologies, Inc. +# +# 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. + +namespace cpp jaegertracing.thrift +namespace java io.jaegertracing.thriftjava +namespace php Jaeger.Thrift.Agent +namespace netcore Jaeger.Thrift.Agent + +struct DependencyLink { + // parent service name (caller) + 1: required string parent + // child service name (callee) + 2: required string child + // calls made during the duration of this link + 4: required i64 callCount +} + +// An aggregate representation of services paired with every service they call. +struct Dependencies { + 1: required list<DependencyLink> links +} + +service Dependency { + Dependencies getDependenciesForTrace(1: required string traceId) + oneway void saveDependencies(1: Dependencies dependencies) +} diff --git a/src/jaegertracing/jaeger-client-cpp/idl/thrift/jaeger.thrift b/src/jaegertracing/jaeger-client-cpp/idl/thrift/jaeger.thrift new file mode 100644 index 000000000..96cc751d9 --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/thrift/jaeger.thrift @@ -0,0 +1,84 @@ +# Copyright (c) 2016 Uber Technologies, Inc. +# +# 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. + +namespace cpp jaegertracing.thrift +namespace java io.jaegertracing.thriftjava +namespace php Jaeger.Thrift +namespace netcore Jaeger.Thrift + +# TagType denotes the type of a Tag's value. +enum TagType { STRING, DOUBLE, BOOL, LONG, BINARY } + +# Tag is a basic strongly typed key/value pair. It has been flattened to reduce the use of pointers in golang +struct Tag { + 1: required string key + 2: required TagType vType + 3: optional string vStr + 4: optional double vDouble + 5: optional bool vBool + 6: optional i64 vLong + 7: optional binary vBinary +} + +# Log is a timed even with an arbitrary set of tags. +struct Log { + 1: required i64 timestamp + 2: required list<Tag> fields +} + +enum SpanRefType { CHILD_OF, FOLLOWS_FROM } + +# SpanRef describes causal relationship of the current span to another span (e.g. 'child-of') +struct SpanRef { + 1: required SpanRefType refType + 2: required i64 traceIdLow + 3: required i64 traceIdHigh + 4: required i64 spanId +} + +# Span represents a named unit of work performed by a service. +struct Span { + 1: required i64 traceIdLow # the least significant 64 bits of a traceID + 2: required i64 traceIdHigh # the most significant 64 bits of a traceID; 0 when only 64bit IDs are used + 3: required i64 spanId # unique span id (only unique within a given trace) + 4: required i64 parentSpanId # since nearly all spans will have parents spans, CHILD_OF refs do not have to be explicit + 5: required string operationName + 6: optional list<SpanRef> references # causal references to other spans + 7: required i32 flags # a bit field used to propagate sampling decisions. 1 signifies a SAMPLED span, 2 signifies a DEBUG span. + 8: required i64 startTime + 9: required i64 duration + 10: optional list<Tag> tags + 11: optional list<Log> logs +} + +# Process describes the traced process/service that emits spans. +struct Process { + 1: required string serviceName + 2: optional list<Tag> tags +} + +# Batch is a collection of spans reported out of process. +struct Batch { + 1: required Process process + 2: required list<Span> spans +} + +# BatchSubmitResponse is the response on submitting a batch. +struct BatchSubmitResponse { + 1: required bool ok # The Collector's client is expected to only log (or emit a counter) when not ok equals false +} + +service Collector { + list<BatchSubmitResponse> submitBatches(1: list<Batch> batches) +} diff --git a/src/jaegertracing/jaeger-client-cpp/idl/thrift/sampling.thrift b/src/jaegertracing/jaeger-client-cpp/idl/thrift/sampling.thrift new file mode 100644 index 000000000..7215eaa71 --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/thrift/sampling.thrift @@ -0,0 +1,58 @@ +# Copyright (c) 2016 Uber Technologies, Inc. +# +# 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. + +namespace cpp jaegertracing.sampling_manager.thrift +namespace java io.jaegertracing.thrift.sampling_manager +namespace php Jaeger.Thrift.Agent +namespace netcore Jaeger.Thrift.Agent + +enum SamplingStrategyType { PROBABILISTIC, RATE_LIMITING } + +// ProbabilisticSamplingStrategy randomly samples a fixed percentage of all traces. +struct ProbabilisticSamplingStrategy { + 1: required double samplingRate // percentage expressed as rate (0..1] +} + +// RateLimitingStrategy samples traces with a rate that does not exceed specified number of traces per second. +// The recommended implementation approach is leaky bucket. +struct RateLimitingSamplingStrategy { + 1: required i16 maxTracesPerSecond +} + +// OperationSamplingStrategy defines a sampling strategy that randomly samples a fixed percentage of operation traces. +struct OperationSamplingStrategy { + 1: required string operation + 2: required ProbabilisticSamplingStrategy probabilisticSampling +} + +// PerOperationSamplingStrategies defines a sampling strategy per each operation name in the service +// with a guaranteed lower bound per second. Once the lower bound is met, operations are randomly sampled +// at a fixed percentage. +struct PerOperationSamplingStrategies { + 1: required double defaultSamplingProbability + 2: required double defaultLowerBoundTracesPerSecond + 3: required list<OperationSamplingStrategy> perOperationStrategies + 4: optional double defaultUpperBoundTracesPerSecond +} + +struct SamplingStrategyResponse { + 1: required SamplingStrategyType strategyType + 2: optional ProbabilisticSamplingStrategy probabilisticSampling + 3: optional RateLimitingSamplingStrategy rateLimitingSampling + 4: optional PerOperationSamplingStrategies operationSampling +} + +service SamplingManager { + SamplingStrategyResponse getSamplingStrategy(1: string serviceName) +} diff --git a/src/jaegertracing/jaeger-client-cpp/idl/thrift/zipkincore.thrift b/src/jaegertracing/jaeger-client-cpp/idl/thrift/zipkincore.thrift new file mode 100644 index 000000000..0bcc7b989 --- /dev/null +++ b/src/jaegertracing/jaeger-client-cpp/idl/thrift/zipkincore.thrift @@ -0,0 +1,344 @@ +# Copyright 2012 Twitter Inc. +# +# 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. +namespace cpp twitter.zipkin.thrift +namespace java com.twitter.zipkin.thriftjava +#@namespace scala com.twitter.zipkin.thriftscala +namespace rb Zipkin +namespace php Jaeger.Thrift.Agent.Zipkin +namespace netcore Jaeger.Thrift.Agent.Zipkin + +#************** Annotation.value ************** +/** + * The client sent ("cs") a request to a server. There is only one send per + * span. For example, if there's a transport error, each attempt can be logged + * as a WIRE_SEND annotation. + * + * If chunking is involved, each chunk could be logged as a separate + * CLIENT_SEND_FRAGMENT in the same span. + * + * Annotation.host is not the server. It is the host which logged the send + * event, almost always the client. When logging CLIENT_SEND, instrumentation + * should also log the SERVER_ADDR. + */ +const string CLIENT_SEND = "cs" +/** + * The client received ("cr") a response from a server. There is only one + * receive per span. For example, if duplicate responses were received, each + * can be logged as a WIRE_RECV annotation. + * + * If chunking is involved, each chunk could be logged as a separate + * CLIENT_RECV_FRAGMENT in the same span. + * + * Annotation.host is not the server. It is the host which logged the receive + * event, almost always the client. The actual endpoint of the server is + * recorded separately as SERVER_ADDR when CLIENT_SEND is logged. + */ +const string CLIENT_RECV = "cr" +/** + * The server sent ("ss") a response to a client. There is only one response + * per span. If there's a transport error, each attempt can be logged as a + * WIRE_SEND annotation. + * + * Typically, a trace ends with a server send, so the last timestamp of a trace + * is often the timestamp of the root span's server send. + * + * If chunking is involved, each chunk could be logged as a separate + * SERVER_SEND_FRAGMENT in the same span. + * + * Annotation.host is not the client. It is the host which logged the send + * event, almost always the server. The actual endpoint of the client is + * recorded separately as CLIENT_ADDR when SERVER_RECV is logged. + */ +const string SERVER_SEND = "ss" +/** + * The server received ("sr") a request from a client. There is only one + * request per span. For example, if duplicate responses were received, each + * can be logged as a WIRE_RECV annotation. + * + * Typically, a trace starts with a server receive, so the first timestamp of a + * trace is often the timestamp of the root span's server receive. + * + * If chunking is involved, each chunk could be logged as a separate + * SERVER_RECV_FRAGMENT in the same span. + * + * Annotation.host is not the client. It is the host which logged the receive + * event, almost always the server. When logging SERVER_RECV, instrumentation + * should also log the CLIENT_ADDR. + */ +const string SERVER_RECV = "sr" +/** + * Message send ("ms") is a request to send a message to a destination, usually + * a broker. This may be the only annotation in a messaging span. If WIRE_SEND + * exists in the same span, it follows this moment and clarifies delays sending + * the message, such as batching. + * + * Unlike RPC annotations like CLIENT_SEND, messaging spans never share a span + * ID. For example, "ms" should always be the parent of "mr". + * + * Annotation.host is not the destination, it is the host which logged the send + * event: the producer. When annotating MESSAGE_SEND, instrumentation should + * also tag the MESSAGE_ADDR. + */ +const string MESSAGE_SEND = "ms" +/** + * A consumer received ("mr") a message from a broker. This may be the only + * annotation in a messaging span. If WIRE_RECV exists in the same span, it + * precedes this moment and clarifies any local queuing delay. + * + * Unlike RPC annotations like SERVER_RECV, messaging spans never share a span + * ID. For example, "mr" should always be a child of "ms" unless it is a root + * span. + * + * Annotation.host is not the broker, it is the host which logged the receive + * event: the consumer. When annotating MESSAGE_RECV, instrumentation should + * also tag the MESSAGE_ADDR. + */ +const string MESSAGE_RECV = "mr" +/** + * Optionally logs an attempt to send a message on the wire. Multiple wire send + * events could indicate network retries. A lag between client or server send + * and wire send might indicate queuing or processing delay. + */ +const string WIRE_SEND = "ws" +/** + * Optionally logs an attempt to receive a message from the wire. Multiple wire + * receive events could indicate network retries. A lag between wire receive + * and client or server receive might indicate queuing or processing delay. + */ +const string WIRE_RECV = "wr" +/** + * Optionally logs progress of a (CLIENT_SEND, WIRE_SEND). For example, this + * could be one chunk in a chunked request. + */ +const string CLIENT_SEND_FRAGMENT = "csf" +/** + * Optionally logs progress of a (CLIENT_RECV, WIRE_RECV). For example, this + * could be one chunk in a chunked response. + */ +const string CLIENT_RECV_FRAGMENT = "crf" +/** + * Optionally logs progress of a (SERVER_SEND, WIRE_SEND). For example, this + * could be one chunk in a chunked response. + */ +const string SERVER_SEND_FRAGMENT = "ssf" +/** + * Optionally logs progress of a (SERVER_RECV, WIRE_RECV). For example, this + * could be one chunk in a chunked request. + */ +const string SERVER_RECV_FRAGMENT = "srf" + +#***** BinaryAnnotation.key ****** +/** + * The value of "lc" is the component or namespace of a local span. + * + * BinaryAnnotation.host adds service context needed to support queries. + * + * Local Component("lc") supports three key features: flagging, query by + * service and filtering Span.name by namespace. + * + * While structurally the same, local spans are fundamentally different than + * RPC spans in how they should be interpreted. For example, zipkin v1 tools + * center on RPC latency and service graphs. Root local-spans are neither + * indicative of critical path RPC latency, nor have impact on the shape of a + * service graph. By flagging with "lc", tools can special-case local spans. + * + * Zipkin v1 Spans are unqueryable unless they can be indexed by service name. + * The only path to a service name is by (Binary)?Annotation.host.serviceName. + * By logging "lc", a local span can be queried even if no other annotations + * are logged. + * + * The value of "lc" is the namespace of Span.name. For example, it might be + * "finatra2", for a span named "bootstrap". "lc" allows you to resolves + * conflicts for the same Span.name, for example "finatra/bootstrap" vs + * "finch/bootstrap". Using local component, you'd search for spans named + * "bootstrap" where "lc=finch" + */ +const string LOCAL_COMPONENT = "lc" + +#***** BinaryAnnotation.key where value = [1] and annotation_type = BOOL ****** +/** + * Indicates a client address ("ca") in a span. Most likely, there's only one. + * Multiple addresses are possible when a client changes its ip or port within + * a span. + */ +const string CLIENT_ADDR = "ca" +/** + * Indicates a server address ("sa") in a span. Most likely, there's only one. + * Multiple addresses are possible when a client is redirected, or fails to a + * different server ip or port. + */ +const string SERVER_ADDR = "sa" +/** + * Indicates the remote address of a messaging span, usually the broker. + */ +const string MESSAGE_ADDR = "ma" + +/** + * Indicates the network context of a service recording an annotation with two + * exceptions. + * + * When a BinaryAnnotation, and key is CLIENT_ADDR or SERVER_ADDR, + * the endpoint indicates the source or destination of an RPC. This exception + * allows zipkin to display network context of uninstrumented services, or + * clients such as web browsers. + */ +struct Endpoint { + /** + * IPv4 host address packed into 4 bytes. + * + * Ex for the ip 1.2.3.4, it would be (1 << 24) | (2 << 16) | (3 << 8) | 4 + */ + 1: i32 ipv4 + /** + * IPv4 port + * + * Note: this is to be treated as an unsigned integer, so watch for negatives. + * + * Conventionally, when the port isn't known, port = 0. + */ + 2: i16 port + /** + * Service name in lowercase, such as "memcache" or "zipkin-web" + * + * Conventionally, when the service name isn't known, service_name = "unknown". + */ + 3: string service_name + /** + * IPv6 host address packed into 16 bytes. Ex Inet6Address.getBytes() + */ + 4: optional binary ipv6 +} + +/** + * An annotation is similar to a log statement. It includes a host field which + * allows these events to be attributed properly, and also aggregatable. + */ +struct Annotation { + /** + * Microseconds from epoch. + * + * This value should use the most precise value possible. For example, + * gettimeofday or syncing nanoTime against a tick of currentTimeMillis. + */ + 1: i64 timestamp + 2: string value // what happened at the timestamp? + /** + * Always the host that recorded the event. By specifying the host you allow + * rollup of all events (such as client requests to a service) by IP address. + */ + 3: optional Endpoint host + // don't reuse 4: optional i32 OBSOLETE_duration // how long did the operation take? microseconds +} + +enum AnnotationType { BOOL, BYTES, I16, I32, I64, DOUBLE, STRING } + +/** + * Binary annotations are tags applied to a Span to give it context. For + * example, a binary annotation of "http.uri" could the path to a resource in a + * RPC call. + * + * Binary annotations of type STRING are always queryable, though more a + * historical implementation detail than a structural concern. + * + * Binary annotations can repeat, and vary on the host. Similar to Annotation, + * the host indicates who logged the event. This allows you to tell the + * difference between the client and server side of the same key. For example, + * the key "http.uri" might be different on the client and server side due to + * rewriting, like "/api/v1/myresource" vs "/myresource. Via the host field, + * you can see the different points of view, which often help in debugging. + */ +struct BinaryAnnotation { + 1: string key, + 2: binary value, + 3: AnnotationType annotation_type, + /** + * The host that recorded tag, which allows you to differentiate between + * multiple tags with the same key. There are two exceptions to this. + * + * When the key is CLIENT_ADDR or SERVER_ADDR, host indicates the source or + * destination of an RPC. This exception allows zipkin to display network + * context of uninstrumented services, or clients such as web browsers. + */ + 4: optional Endpoint host +} + +/** + * A trace is a series of spans (often RPC calls) which form a latency tree. + * + * The root span is where trace_id = id and parent_id = Nil. The root span is + * usually the longest interval in the trace, starting with a SERVER_RECV + * annotation and ending with a SERVER_SEND. + */ +struct Span { + 1: i64 trace_id # unique trace id, use for all spans in trace + /** + * Span name in lowercase, rpc method for example + * + * Conventionally, when the span name isn't known, name = "unknown". + */ + 3: string name, + 4: i64 id, # unique span id, only used for this span + 5: optional i64 parent_id, # parent span id + 6: list<Annotation> annotations, # all annotations/events that occured, sorted by timestamp + 8: list<BinaryAnnotation> binary_annotations # any binary annotations + 9: optional bool debug = 0 # if true, we DEMAND that this span passes all samplers + /** + * Microseconds from epoch of the creation of this span. + * + * This value should be set directly by instrumentation, using the most + * precise value possible. For example, gettimeofday or syncing nanoTime + * against a tick of currentTimeMillis. + * + * For compatibilty with instrumentation that precede this field, collectors + * or span stores can derive this via Annotation.timestamp. + * For example, SERVER_RECV.timestamp or CLIENT_SEND.timestamp. + * + * This field is optional for compatibility with old data: first-party span + * stores are expected to support this at time of introduction. + */ + 10: optional i64 timestamp, + /** + * Measurement of duration in microseconds, used to support queries. + * + * This value should be set directly, where possible. Doing so encourages + * precise measurement decoupled from problems of clocks, such as skew or NTP + * updates causing time to move backwards. + * + * For compatibilty with instrumentation that precede this field, collectors + * or span stores can derive this by subtracting Annotation.timestamp. + * For example, SERVER_SEND.timestamp - SERVER_RECV.timestamp. + * + * If this field is persisted as unset, zipkin will continue to work, except + * duration query support will be implementation-specific. Similarly, setting + * this field non-atomically is implementation-specific. + * + * This field is i64 vs i32 to support spans longer than 35 minutes. + */ + 11: optional i64 duration + /** + * Optional unique 8-byte additional identifier for a trace. If non zero, this + * means the trace uses 128 bit traceIds instead of 64 bit. + */ + 12: optional i64 trace_id_high +} + +# define TChannel service + +struct Response { + 1: required bool ok +} + +service ZipkinCollector { + list<Response> submitZipkinBatch(1: list<Span> spans) +} |