├── .drone.yml ├── .github └── rvu │ └── labels.yaml ├── .gitignore ├── CHANGELOG.md ├── LICENSE ├── README.md ├── project.clj └── src └── opencensus_clojure ├── propagation.clj ├── reporting ├── jaeger.clj ├── logging.clj └── zipkin.clj ├── ring └── middleware.clj └── trace.clj /.drone.yml: -------------------------------------------------------------------------------- 1 | clone: 2 | git: 3 | image: plugins/git 4 | depth: 1 5 | 6 | pipeline: 7 | release: 8 | image: registry.usw.co/uswitch/clojure 9 | secrets: [ CLOJARS_USERNAME, CLOJARS_PASSWORD ] 10 | when: 11 | branch: master 12 | event: push 13 | commands: 14 | - lein deps 15 | - lein codox 16 | - lein jar 17 | - lein deploy clojars 18 | 19 | build-gh-pages: 20 | image: registry.usw.co/uswitch/clojure 21 | when: 22 | branch: master 23 | event: push 24 | commands: 25 | - lein codox 26 | - mkdir .docs && mv target/doc/* .docs/ 27 | - rm -r * && rm .gitignore && rm .drone.yml 28 | - mv .docs/* . && rmdir .docs 29 | 30 | commit-gh-pages: 31 | image: plugins/git 32 | when: 33 | branch: master 34 | event: push 35 | commands: 36 | - git config user.name dodgydrone 37 | - git config user.email drone@drone.drone 38 | - git checkout --orphan gh-pages 39 | - git add . 40 | - git commit -m "dox" 41 | 42 | git_push: 43 | image: appleboy/drone-git-push 44 | secrets: [ DRONE_NETRC_USERNAME, DRONE_NETRC_PASSWORD ] 45 | when: 46 | branch: master 47 | event: push 48 | remote: https://github.com/uswitch/opencensus-clojure.git 49 | branch: gh-pages 50 | local_ref: gh-pages 51 | force: true 52 | -------------------------------------------------------------------------------- /.github/rvu/labels.yaml: -------------------------------------------------------------------------------- 1 | service.rvu.co.uk/owner: hs-cj-energy 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /target 2 | /classes 3 | /checkouts 4 | pom.xml 5 | pom.xml.asc 6 | *.jar 7 | *.class 8 | /.lein-* 9 | /.nrepl-port 10 | .hgignore 11 | .hg/ 12 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | ## v0.2.x 2 | 3 | - change the `span` interface 4 | - the `debug` option is gone. Use `opencensus-clojure.trace/configure-tracer` and 5 | set `p=1.0` to guarantee sampling 6 | - span now takes an optional remote parent `SpanContext` 7 | - Ring middleware automatically extracts this using the B3 format used by istio etc. 8 | - added function to generate headers for downstream requests in B3 format 9 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Eclipse Public License - v 1.0 2 | 3 | THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC 4 | LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE PROGRAM 5 | CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. 6 | 7 | 1. DEFINITIONS 8 | 9 | "Contribution" means: 10 | 11 | a) in the case of the initial Contributor, the initial code and documentation 12 | distributed under this Agreement, and 13 | b) in the case of each subsequent Contributor: 14 | i) changes to the Program, and 15 | ii) additions to the Program; 16 | 17 | where such changes and/or additions to the Program originate from and are 18 | distributed by that particular Contributor. A Contribution 'originates' 19 | from a Contributor if it was added to the Program by such Contributor 20 | itself or anyone acting on such Contributor's behalf. Contributions do not 21 | include additions to the Program which: (i) are separate modules of 22 | software distributed in conjunction with the Program under their own 23 | license agreement, and (ii) are not derivative works of the Program. 24 | 25 | "Contributor" means any person or entity that distributes the Program. 26 | 27 | "Licensed Patents" mean patent claims licensable by a Contributor which are 28 | necessarily infringed by the use or sale of its Contribution alone or when 29 | combined with the Program. 30 | 31 | "Program" means the Contributions distributed in accordance with this 32 | Agreement. 33 | 34 | "Recipient" means anyone who receives the Program under this Agreement, 35 | including all Contributors. 36 | 37 | 2. GRANT OF RIGHTS 38 | a) Subject to the terms of this Agreement, each Contributor hereby grants 39 | Recipient a non-exclusive, worldwide, royalty-free copyright license to 40 | reproduce, prepare derivative works of, publicly display, publicly 41 | perform, distribute and sublicense the Contribution of such Contributor, 42 | if any, and such derivative works, in source code and object code form. 43 | b) Subject to the terms of this Agreement, each Contributor hereby grants 44 | Recipient a non-exclusive, worldwide, royalty-free patent license under 45 | Licensed Patents to make, use, sell, offer to sell, import and otherwise 46 | transfer the Contribution of such Contributor, if any, in source code and 47 | object code form. This patent license shall apply to the combination of 48 | the Contribution and the Program if, at the time the Contribution is 49 | added by the Contributor, such addition of the Contribution causes such 50 | combination to be covered by the Licensed Patents. The patent license 51 | shall not apply to any other combinations which include the Contribution. 52 | No hardware per se is licensed hereunder. 53 | c) Recipient understands that although each Contributor grants the licenses 54 | to its Contributions set forth herein, no assurances are provided by any 55 | Contributor that the Program does not infringe the patent or other 56 | intellectual property rights of any other entity. Each Contributor 57 | disclaims any liability to Recipient for claims brought by any other 58 | entity based on infringement of intellectual property rights or 59 | otherwise. As a condition to exercising the rights and licenses granted 60 | hereunder, each Recipient hereby assumes sole responsibility to secure 61 | any other intellectual property rights needed, if any. For example, if a 62 | third party patent license is required to allow Recipient to distribute 63 | the Program, it is Recipient's responsibility to acquire that license 64 | before distributing the Program. 65 | d) Each Contributor represents that to its knowledge it has sufficient 66 | copyright rights in its Contribution, if any, to grant the copyright 67 | license set forth in this Agreement. 68 | 69 | 3. REQUIREMENTS 70 | 71 | A Contributor may choose to distribute the Program in object code form under 72 | its own license agreement, provided that: 73 | 74 | a) it complies with the terms and conditions of this Agreement; and 75 | b) its license agreement: 76 | i) effectively disclaims on behalf of all Contributors all warranties 77 | and conditions, express and implied, including warranties or 78 | conditions of title and non-infringement, and implied warranties or 79 | conditions of merchantability and fitness for a particular purpose; 80 | ii) effectively excludes on behalf of all Contributors all liability for 81 | damages, including direct, indirect, special, incidental and 82 | consequential damages, such as lost profits; 83 | iii) states that any provisions which differ from this Agreement are 84 | offered by that Contributor alone and not by any other party; and 85 | iv) states that source code for the Program is available from such 86 | Contributor, and informs licensees how to obtain it in a reasonable 87 | manner on or through a medium customarily used for software exchange. 88 | 89 | When the Program is made available in source code form: 90 | 91 | a) it must be made available under this Agreement; and 92 | b) a copy of this Agreement must be included with each copy of the Program. 93 | Contributors may not remove or alter any copyright notices contained 94 | within the Program. 95 | 96 | Each Contributor must identify itself as the originator of its Contribution, 97 | if 98 | any, in a manner that reasonably allows subsequent Recipients to identify the 99 | originator of the Contribution. 100 | 101 | 4. COMMERCIAL DISTRIBUTION 102 | 103 | Commercial distributors of software may accept certain responsibilities with 104 | respect to end users, business partners and the like. While this license is 105 | intended to facilitate the commercial use of the Program, the Contributor who 106 | includes the Program in a commercial product offering should do so in a manner 107 | which does not create potential liability for other Contributors. Therefore, 108 | if a Contributor includes the Program in a commercial product offering, such 109 | Contributor ("Commercial Contributor") hereby agrees to defend and indemnify 110 | every other Contributor ("Indemnified Contributor") against any losses, 111 | damages and costs (collectively "Losses") arising from claims, lawsuits and 112 | other legal actions brought by a third party against the Indemnified 113 | Contributor to the extent caused by the acts or omissions of such Commercial 114 | Contributor in connection with its distribution of the Program in a commercial 115 | product offering. The obligations in this section do not apply to any claims 116 | or Losses relating to any actual or alleged intellectual property 117 | infringement. In order to qualify, an Indemnified Contributor must: 118 | a) promptly notify the Commercial Contributor in writing of such claim, and 119 | b) allow the Commercial Contributor to control, and cooperate with the 120 | Commercial Contributor in, the defense and any related settlement 121 | negotiations. The Indemnified Contributor may participate in any such claim at 122 | its own expense. 123 | 124 | For example, a Contributor might include the Program in a commercial product 125 | offering, Product X. That Contributor is then a Commercial Contributor. If 126 | that Commercial Contributor then makes performance claims, or offers 127 | warranties related to Product X, those performance claims and warranties are 128 | such Commercial Contributor's responsibility alone. Under this section, the 129 | Commercial Contributor would have to defend claims against the other 130 | Contributors related to those performance claims and warranties, and if a 131 | court requires any other Contributor to pay any damages as a result, the 132 | Commercial Contributor must pay those damages. 133 | 134 | 5. NO WARRANTY 135 | 136 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN 137 | "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR 138 | IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, 139 | NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each 140 | Recipient is solely responsible for determining the appropriateness of using 141 | and distributing the Program and assumes all risks associated with its 142 | exercise of rights under this Agreement , including but not limited to the 143 | risks and costs of program errors, compliance with applicable laws, damage to 144 | or loss of data, programs or equipment, and unavailability or interruption of 145 | operations. 146 | 147 | 6. DISCLAIMER OF LIABILITY 148 | 149 | EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY 150 | CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, 151 | SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION 152 | LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 153 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 154 | ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE 155 | EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY 156 | OF SUCH DAMAGES. 157 | 158 | 7. GENERAL 159 | 160 | If any provision of this Agreement is invalid or unenforceable under 161 | applicable law, it shall not affect the validity or enforceability of the 162 | remainder of the terms of this Agreement, and without further action by the 163 | parties hereto, such provision shall be reformed to the minimum extent 164 | necessary to make such provision valid and enforceable. 165 | 166 | If Recipient institutes patent litigation against any entity (including a 167 | cross-claim or counterclaim in a lawsuit) alleging that the Program itself 168 | (excluding combinations of the Program with other software or hardware) 169 | infringes such Recipient's patent(s), then such Recipient's rights granted 170 | under Section 2(b) shall terminate as of the date such litigation is filed. 171 | 172 | All Recipient's rights under this Agreement shall terminate if it fails to 173 | comply with any of the material terms or conditions of this Agreement and does 174 | not cure such failure in a reasonable period of time after becoming aware of 175 | such noncompliance. If all Recipient's rights under this Agreement terminate, 176 | Recipient agrees to cease use and distribution of the Program as soon as 177 | reasonably practicable. However, Recipient's obligations under this Agreement 178 | and any licenses granted by Recipient relating to the Program shall continue 179 | and survive. 180 | 181 | Everyone is permitted to copy and distribute copies of this Agreement, but in 182 | order to avoid inconsistency the Agreement is copyrighted and may only be 183 | modified in the following manner. The Agreement Steward reserves the right to 184 | publish new versions (including revisions) of this Agreement from time to 185 | time. No one other than the Agreement Steward has the right to modify this 186 | Agreement. The Eclipse Foundation is the initial Agreement Steward. The 187 | Eclipse Foundation may assign the responsibility to serve as the Agreement 188 | Steward to a suitable separate entity. Each new version of the Agreement will 189 | be given a distinguishing version number. The Program (including 190 | Contributions) may always be distributed subject to the version of the 191 | Agreement under which it was received. In addition, after a new version of the 192 | Agreement is published, Contributor may elect to distribute the Program 193 | (including its Contributions) under the new version. Except as expressly 194 | stated in Sections 2(a) and 2(b) above, Recipient receives no rights or 195 | licenses to the intellectual property of any Contributor under this Agreement, 196 | whether expressly, by implication, estoppel or otherwise. All rights in the 197 | Program not expressly granted under this Agreement are reserved. 198 | 199 | This Agreement is governed by the laws of the State of New York and the 200 | intellectual property laws of the United States of America. No party to this 201 | Agreement will bring a legal action under this Agreement more than one year 202 | after the cause of action arose. Each party waives its rights to a jury trial in 203 | any resulting litigation. 204 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # DEPRECATED and ARCHIVED. 2 | 3 | See 4 | https://github.com/uswitch/service-standard-clj 5 | 6 | and 7 | https://github.com/uswitch/service-standard-clj/blob/main/src/uswitch_service_standard/tracing/tracing.md 8 | 9 | 10 | 11 | # opencensus-clojure 12 | 13 | A Clojure library designed to pass butter. 14 | 15 | **** 16 | **NOTE**: this is __**alpha**__ software under active development; here be dragons. 17 | **** 18 | 19 | ## Usage 20 | 21 | ## Dependency 22 | 23 | Add the latest 24 | 25 | [![Clojars Project](http://clojars.org/uswitch/opencensus-clojure/latest-version.svg)](http://clojars.org/uswitch/opencensus-clojure) 26 | 27 | to your build tool of choice, **AND** add your preferred exporter lib, e.g., 28 | `[io.opencensus/opencensus-exporter-trace-zipkin "0.19.2"]`. This is because there are at least 5 exporters and we don't 29 | want to pull in a boatload of unneeded transitives. 30 | 31 | ### Ring 32 | There's a ringleware that you can use like this 33 | ```clojure 34 | (ns another-web-app 35 | (:require [opencensus-clojure.ring.middleware :refer [wrap-tracing]] 36 | [clojure.string :as str] 37 | [compojure.api.sweet :refer :all])) 38 | 39 | (defroutes handlers 40 | (GET "/foo" (ok "bar"))) 41 | 42 | ; will assume all your requests are the same and use "ring-request" for the operation name 43 | (-> handlers 44 | (wrap-tracing)) 45 | 46 | ; will take a function to figure out the name of the operation from the request. For a ring app, it 47 | ; _probably_ makes sense to pass :uri, meaning the path would be the operation name 48 | (-> handlers 49 | (wrap-tracing (fn [req] (-> req :uri (str/replace #"/" "🦄"))))) 50 | 51 | ``` 52 | 53 | It also adds a tag with the response status by default. 54 | 55 | ### Generic 56 | 57 | The ringleware essentially just wraps the more generic macro, `span`, which takes an op name 58 | and an arbitrary form. 59 | 60 | ```clojure 61 | (ns my-deep-layered-namespace 62 | (:require [opencensus-clojure.trace :refer [span add-tag]])) 63 | 64 | (defn fetch-sticks 65 | "fetches sticks and is a good boi" 66 | [stick-filters] 67 | (span "my-operation-name" 68 | (let [db-response (do-a-db-thing stick-filters)] 69 | (add-tag "did-the-db-thing-succeed" (:success db-response))))) 70 | ``` 71 | As in the example, you can also add tags anywhere inside a `span`. Because the ringleware wraps a request, 72 | you can in theory do this anywhere within a request, but the tag will end up on whatever span is currently 73 | being measured. 74 | 75 | The nesting is handled by magic under the bonnet, so you **can** literally just wrap ring and then do these 76 | `span`s in your DB layer, and get nice nested timings out of this. 77 | 78 | ### Distributed tracing 79 | 80 | The ring middleware will automagically pick up Zipkin B3 format headers and assign the remote context if it finds one. 81 | 82 | To pass trace IDs downstream, use `(opencensus-clojure.trace/make-downstream-headers)` anywhere within a traced context. 83 | 84 | Example: 85 | ```clojure 86 | (span "foobar" 87 | (http-kit/get "http://google.com/all-your-base" 88 | {:headers (trace/make-downstream-headers)})) 89 | ``` 90 | 91 | As above, keep in mind that Ring already wraps a span, so you can do this pretty much anywhere within your app. 92 | The function returns a `{str str}`, which is what most HTTP clients understand 93 | 94 | ### Reporting 95 | 96 | There are multiple reporters available. 97 | 98 | The `logging` one 99 | ```clojure 100 | (opencensus-clojure.reporting.logging/report) 101 | ``` 102 | 103 | The Jaeger one 104 | ```clojure 105 | (opencensus-clojure.reporting.jaeger/report "my-service-name") 106 | 107 | ; allows you to specify the Thrift HTTP endpoint manually 108 | (opencensus-clojure.reporting.jaeger/report "http://localhost:14268/api/traces" "my-service-name") 109 | ``` 110 | 111 | The Zipkin one 112 | ```clojure 113 | (opencensus-clojure.reporting.zipkin/report "my-service-name") 114 | 115 | ; allows you to specify the HTTP endpoint manually 116 | (opencensus-clojure.reporting.jaeger/report "http://localhost:9411/api/v2/spans" "my-service-name") 117 | ``` 118 | 119 | The logging one is nice to figure out if your stuff is working in the first place if your Jaeger or Zipkin thing seems 120 | to not be. 121 | 122 | You can launch a batteries included Jaeger thing via 123 | ```shell 124 | $ docker run --rm -i \ 125 | -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \ 126 | -p5775:5775/udp -p6831:6831/udp -p6832:6832/udp \ 127 | -p5778:5778 -p16686:16686 -p14268:14268 -p9411:9411 \ 128 | jaegertracing/all-in-one:latest 129 | ``` 130 | It should come up with a UI on `localhost:16686`, and you should see all your traces there. 131 | 132 | Launching a local Zipkin handler is up to you. 133 | 134 | #### Configuration 135 | 136 | The traces are probabilistic by default; you can configure the tracer to `p=1.0` via 137 | ```clojure 138 | (opencensus-clojure.trace/configure-tracer {:probability 1.0}) 139 | ``` 140 | to force sampling. The configuration function also takes 141 | - `max-annotations` 142 | - `max-attributes` 143 | - `max-links` 144 | - `max-message-events` 145 | 146 | ## Disclaimer 147 | 148 | This relies on 149 | - [opencensus-java](https://www.javadoc.io/doc/io.opencensus/opencensus-api/0.12.3) 150 | - [github](https://github.com/census-instrumentation/opencensus-java) 151 | - single-threadedness for the duration of a span. I.e., your usual Ring + Jetty should work just fine. 152 | If you're doing futures inside your requests and try doing spans in said futures, it will probably 153 | get funny. Have done no testing there, so that way be dragons. 154 | Async Ring and other green thread stuff will probably get funny. 155 | OpenCensus supports directly passing in parent spans etc., and we can extend it to be 156 | async/threading-compatible if there's actual demand. 157 | 158 | # License 159 | 160 | Copyright © 2018 uSwitch 161 | 162 | Distributed under the Eclipse Public License, the same as Clojure. 163 | -------------------------------------------------------------------------------- /project.clj: -------------------------------------------------------------------------------- 1 | (def base-version "0.2") 2 | 3 | (defproject uswitch/opencensus-clojure (str base-version (if-let [number (System/getenv "DRONE_BUILD_NUMBER")] (str "." number) "-SNAPSHOT")) 4 | :description "wraps opencensus-java" 5 | :url "https://github.com/uswitch/opencensus-java" 6 | :scm {:name "git" 7 | :url "https://github.com/uswitch/opencensus-java"} 8 | :license {:name "Eclipse Public License" 9 | :url "http://www.eclipse.org/legal/epl-v10.html"} 10 | :plugins [[lein-codox "0.10.3"]] 11 | :codox {:metadata {:doc/format :markdown}} 12 | :dependencies [[org.clojure/clojure "1.9.0" :scope "provided"] 13 | [org.clojure/tools.logging "0.4.0"] 14 | [io.opencensus/opencensus-api "0.19.2"] 15 | [io.opencensus/opencensus-impl "0.19.2" :scope "runtime"] 16 | [io.opencensus/opencensus-exporter-trace-logging "0.19.2" :scope "provided"] 17 | [io.opencensus/opencensus-exporter-trace-jaeger "0.19.2" :scope "provided"] 18 | [io.opencensus/opencensus-exporter-trace-zipkin "0.19.2" :scope "provided"]] 19 | 20 | :repositories [["clojars" {:sign-releases false 21 | :username [:gpg :env/clojars_username] 22 | :password [:gpg :env/clojars_password]}]] 23 | :deploy-repositories [["clojars" {:sign-releases false 24 | :username [:gpg :env/clojars_username] 25 | :password [:gpg :env/clojars_password]}]]) 26 | -------------------------------------------------------------------------------- /src/opencensus_clojure/propagation.clj: -------------------------------------------------------------------------------- 1 | (ns ^:no-doc opencensus-clojure.propagation 2 | "Contains implementations to [de]serialize `SpanContext`s to / from B3 headers. These are almost certainly not the 3 | droids you're looking for." 4 | (:refer-clojure :rename {get core-get 5 | set core-set}) 6 | (:require [clojure.string :as str]) 7 | (:import (io.opencensus.trace.propagation TextFormat$Getter TextFormat$Setter))) 8 | 9 | (def ring-b3-getter 10 | (proxy [TextFormat$Getter] [] 11 | (get [request key] 12 | (let [headers (:headers request)] 13 | (core-get headers (str/lower-case key)))))) 14 | 15 | (def b3-setter 16 | (proxy [TextFormat$Setter] [] 17 | (put [transient-hash key value] 18 | (assoc! transient-hash (str/lower-case key) value)))) 19 | -------------------------------------------------------------------------------- /src/opencensus_clojure/reporting/jaeger.clj: -------------------------------------------------------------------------------- 1 | (ns opencensus-clojure.reporting.jaeger 2 | (:require [clojure.tools.logging :as log]) 3 | (:import (io.opencensus.exporter.trace.jaeger JaegerTraceExporter))) 4 | 5 | (defn report 6 | "Reports the spans to Jaeger. 7 | 8 | - `:endpoint` optional endpoint to report to 9 | - `:service-name` the name of your app. This is global and forever." 10 | ([^String service-name] (report "http://localhost:14268/api/traces" service-name)) 11 | ([^String endpoint ^String service-name] 12 | (do 13 | (log/info "starting Jaeger reporter") 14 | (JaegerTraceExporter/createAndRegister endpoint service-name)))) 15 | 16 | (defn shutdown [] 17 | "Unregisters the trace exporter" 18 | (JaegerTraceExporter/unregister)) 19 | -------------------------------------------------------------------------------- /src/opencensus_clojure/reporting/logging.clj: -------------------------------------------------------------------------------- 1 | (ns opencensus-clojure.reporting.logging 2 | (:require [clojure.tools.logging :as log]) 3 | (:import (io.opencensus.exporter.trace.logging LoggingTraceExporter))) 4 | 5 | 6 | (defn report 7 | "Reports your spans via logging. Useful for debugging, to see that your spans actually work." 8 | [] 9 | (do 10 | (log/info "starting logging reporter") 11 | (LoggingTraceExporter/register))) 12 | 13 | (defn shutdown [] 14 | "Unregisters the trace exporter" 15 | (LoggingTraceExporter/unregister)) 16 | -------------------------------------------------------------------------------- /src/opencensus_clojure/reporting/zipkin.clj: -------------------------------------------------------------------------------- 1 | (ns opencensus-clojure.reporting.zipkin 2 | (:require [clojure.tools.logging :as log]) 3 | (:import (io.opencensus.exporter.trace.zipkin ZipkinTraceExporter))) 4 | 5 | (defn report 6 | "Reports the spans to Zipkin. 7 | 8 | - `:endpoint` optional endpoint to report to 9 | - `:service-name` the name of your app. This is global and forever." 10 | ([^String service-name] (report "http://localhost:9411/api/v2/spans" service-name)) 11 | ([^String endpoint ^String service-name] (do 12 | (log/info "starting Zipkin reporter") 13 | (ZipkinTraceExporter/createAndRegister endpoint service-name)))) 14 | 15 | (defn shutdown [] 16 | "Unregisters the trace exporter" 17 | (ZipkinTraceExporter/unregister)) 18 | -------------------------------------------------------------------------------- /src/opencensus_clojure/ring/middleware.clj: -------------------------------------------------------------------------------- 1 | (ns opencensus-clojure.ring.middleware 2 | (:require [opencensus-clojure.trace :refer [span add-tag]] 3 | [clojure.tools.logging :as logging] 4 | [opencensus-clojure.propagation :refer [ring-b3-getter b3-setter]]) 5 | (:import (io.opencensus.trace Tracing) 6 | (io.opencensus.trace.propagation TextFormat))) 7 | 8 | (defn- extract-remote-span [{:keys [headers] :as request}] 9 | (when (get headers "x-b3-traceid") 10 | (logging/debug "found x-b3-spanid, extracting remote context") 11 | (let [^TextFormat b3-format (-> (Tracing/getPropagationComponent) (.getB3Format))] 12 | (.extract b3-format request ring-b3-getter)))) 13 | 14 | (defn wrap-tracing 15 | "Ring middleware that wraps span tracing around a ring handler. 16 | 17 | - `:handler` the ring handler 18 | - `:name-foo` a 1-arg function that takes the request and returns a string, used to figure out the operation name for 19 | the span. A common example might be `:uri`, if your paths don't have variables in them." 20 | ([handler] 21 | (fn [req] 22 | (span "ring-request" 23 | (let [response (handler req)] 24 | (add-tag "http_status" (:status response)) 25 | response) 26 | (extract-remote-span req)))) 27 | 28 | ([handler name-foo] 29 | (fn [req] 30 | (span (name-foo req) 31 | (let [response (handler req)] 32 | (add-tag "http_status" (:status response)) 33 | response) 34 | (extract-remote-span req))))) 35 | -------------------------------------------------------------------------------- /src/opencensus_clojure/trace.clj: -------------------------------------------------------------------------------- 1 | (ns opencensus-clojure.trace 2 | (:require [opencensus-clojure.propagation :refer [b3-setter]] 3 | [clojure.tools.logging :as log]) 4 | (:import (io.opencensus.trace Tracing AttributeValue Tracer Span SpanContext SpanBuilder) 5 | (io.opencensus.trace.samplers Samplers) 6 | (io.opencensus.trace.config TraceConfig TraceParams$Builder) 7 | (io.opencensus.trace.propagation TextFormat))) 8 | 9 | ; these have to be "public" because the macros use them. They're not actually "public". 10 | (def ^:no-doc ^Tracer tracer 11 | "NOTE public because the macros use it; not to actually be consumed by clients" 12 | (Tracing/getTracer)) 13 | 14 | (def ^{:dynamic true :no-doc true} ^Span current-span 15 | "NOTE public because the macros use it; not to actually be consumed by clients" 16 | nil) 17 | 18 | (defn configure-tracer 19 | "Configure the underlying tracer. Takes 20 | 21 | - `:probability` 22 | - `:max-annotations` 23 | - `:max-attributes` 24 | - `:max-links` 25 | - `:max-message-events` 26 | 27 | all of which are proxied through to the [TraceParams](https://static.javadoc.io/io.opencensus/opencensus-api/0.13.0/io/opencensus/trace/config/TraceParams.html) class." 28 | [{:keys [probability max-annotations max-attributes max-links max-message-events]}] 29 | (let [^TraceConfig trace-config (Tracing/getTraceConfig) 30 | ^TraceParams$Builder new-params-builder (-> trace-config 31 | (.getActiveTraceParams) 32 | (.toBuilder))] 33 | (do 34 | (when (some? probability) 35 | (.setSampler new-params-builder (Samplers/probabilitySampler probability))) 36 | (when (some? max-annotations) 37 | (.setMaxNumberOfAnnotations new-params-builder max-annotations)) 38 | (when (some? max-attributes) 39 | (.setMaxNumberOfAttributes new-params-builder max-attributes)) 40 | (when (some? max-links) 41 | (.setMaxNumberOfLinks new-params-builder max-links)) 42 | (when (some? max-message-events) 43 | (.setMaxNumberOfMessageEvents new-params-builder max-message-events)) 44 | (.updateActiveTraceParams trace-config (.build new-params-builder))))) 45 | 46 | (defn- value->AttributeValue 47 | [v] 48 | (cond 49 | (int? v) (AttributeValue/longAttributeValue v) 50 | (boolean? v) (AttributeValue/booleanAttributeValue v) 51 | :else (AttributeValue/stringAttributeValue (str v)))) 52 | 53 | (defn add-tag 54 | "Adds a tag on the current span 55 | 56 | - `:k` tag name 57 | - `:v` tag value. Natively supported types are long, bool or string" 58 | [^String k ^Object v] 59 | (.putAttribute 60 | current-span 61 | k 62 | (value->AttributeValue v))) 63 | 64 | (defn add-tags 65 | "See [[add-tag]]`. 66 | 67 | - `:tags` a hash of key-value pairs you'd pass to `add-tag`." 68 | [tags] 69 | (.putAttributes 70 | current-span 71 | (->> tags 72 | (map (fn [[k v]] [k (value->AttributeValue v)])) 73 | (into {})))) 74 | 75 | (defn make-downstream-headers 76 | "Produces B3 style headers for the current span, to be passed down into further RPCs for distributed tracing." 77 | [] 78 | (let [^TextFormat b3-format (-> (Tracing/getPropagationComponent) (.getB3Format)) 79 | builder (transient {})] 80 | (.inject b3-format (.getContext current-span) builder b3-setter) 81 | (persistent! builder))) 82 | 83 | (defmacro span 84 | "Creates a traced span. Takes a name and a form to be traced, or, additionally, a remote `SpanContext` that is a 85 | remote parent of the one you're starting. 86 | 87 | It is expected that clients should mostly use the 2-arg form and the 3-ard form is called from the Ring middleware 88 | handling the deserialization of the context from B3 headers, however, if you're not using Ring, this might be useful." 89 | ([^String span-name code] 90 | `(let [^SpanBuilder span-builder# (.spanBuilder tracer ~span-name)] 91 | (log/debug "building span " ~span-name) 92 | (with-open [scope# (.startScopedSpan span-builder#)] 93 | (binding [current-span (.getCurrentSpan tracer)] 94 | ~code)))) 95 | 96 | ([^String span-name code ^SpanContext remote] 97 | `(let [^SpanBuilder span-builder# (.spanBuilderWithRemoteParent tracer ~span-name ~remote)] 98 | (log/debug "building span " ~span-name " with remote parent") 99 | (with-open [scope# (.startScopedSpan span-builder#)] 100 | (binding [current-span (.getCurrentSpan tracer)] 101 | ~code))))) 102 | --------------------------------------------------------------------------------