{"id":13761661,"url":"https://github.com/uswitch/opencensus-clojure","last_synced_at":"2025-05-10T14:30:32.605Z","repository":{"id":48880259,"uuid":"131319029","full_name":"uswitch/opencensus-clojure","owner":"uswitch","description":null,"archived":true,"fork":false,"pushed_at":"2024-11-07T15:17:01.000Z","size":84,"stargazers_count":15,"open_issues_count":1,"forks_count":1,"subscribers_count":46,"default_branch":"master","last_synced_at":"2024-11-16T20:30:45.003Z","etag":null,"topics":["clojure","cloud","distributed-tracing","jaeger","opencensus","ring","stats","trace","tracing","zipkin"],"latest_commit_sha":null,"homepage":"https://uswitch.github.io/opencensus-clojure/","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uswitch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-27T16:13:04.000Z","updated_at":"2024-11-07T15:20:21.000Z","dependencies_parsed_at":"2024-11-17T00:19:09.405Z","dependency_job_id":null,"html_url":"https://github.com/uswitch/opencensus-clojure","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fopencensus-clojure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fopencensus-clojure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fopencensus-clojure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fopencensus-clojure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uswitch","download_url":"https://codeload.github.com/uswitch/opencensus-clojure/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253428171,"owners_count":21906862,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clojure","cloud","distributed-tracing","jaeger","opencensus","ring","stats","trace","tracing","zipkin"],"created_at":"2024-08-03T14:00:21.611Z","updated_at":"2025-05-10T14:30:32.317Z","avatar_url":"https://github.com/uswitch.png","language":"Clojure","funding_links":[],"categories":["Integrations"],"sub_categories":["Clojure"],"readme":"# DEPRECATED and ARCHIVED.\n\nSee \nhttps://github.com/uswitch/service-standard-clj \n\nand \nhttps://github.com/uswitch/service-standard-clj/blob/main/src/uswitch_service_standard/tracing/tracing.md\n\n\n\n# opencensus-clojure\n\nA Clojure library designed to pass butter.\n\n****\n**NOTE**: this is __**alpha**__ software under active development; here be dragons.\n****\n\n## Usage\n\n## Dependency\n\nAdd the latest \n\n[![Clojars Project](http://clojars.org/uswitch/opencensus-clojure/latest-version.svg)](http://clojars.org/uswitch/opencensus-clojure) \n\nto your build tool of choice, **AND** add your preferred exporter lib, e.g.,\n`[io.opencensus/opencensus-exporter-trace-zipkin \"0.19.2\"]`. This is because there are at least 5 exporters and we don't\nwant to pull in a boatload of unneeded transitives.\n\n### Ring\nThere's a ringleware that you can use like this\n```clojure\n(ns another-web-app\n  (:require [opencensus-clojure.ring.middleware :refer [wrap-tracing]]\n            [clojure.string :as str]\n            [compojure.api.sweet :refer :all]))\n\n(defroutes handlers\n  (GET \"/foo\" (ok \"bar\")))\n\n; will assume all your requests are the same and use \"ring-request\" for the operation name\n(-\u003e handlers\n  (wrap-tracing))\n\n; will take a function to figure out the name of the operation from the request. For a ring app, it\n; _probably_ makes sense to pass :uri, meaning the path would be the operation name\n(-\u003e handlers\n  (wrap-tracing (fn [req] (-\u003e req :uri (str/replace #\"/\" \"🦄\")))))\n\n```\n\nIt also adds a tag with the response status by default.\n\n### Generic\n\nThe ringleware essentially just wraps the more generic macro, `span`, which takes an op name \nand an arbitrary form.\n\n```clojure\n(ns my-deep-layered-namespace\n  (:require [opencensus-clojure.trace :refer [span add-tag]]))\n\n(defn fetch-sticks\n  \"fetches sticks and is a good boi\" \n  [stick-filters]\n  (span \"my-operation-name\"\n    (let [db-response (do-a-db-thing stick-filters)]\n      (add-tag \"did-the-db-thing-succeed\" (:success db-response)))))\n```\nAs in the example, you can also add tags anywhere inside a `span`. Because the ringleware wraps a request,\nyou can in theory do this anywhere within a request, but the tag will end up on whatever span is currently\nbeing measured.\n\nThe nesting is handled by magic under the bonnet, so you **can** literally just wrap ring and then do these\n`span`s in your DB layer, and get nice nested timings out of this.\n\n### Distributed tracing\n\nThe ring middleware will automagically pick up Zipkin B3 format headers and assign the remote context if it finds one.\n\nTo pass trace IDs downstream, use `(opencensus-clojure.trace/make-downstream-headers)` anywhere within a traced context.\n\nExample:\n```clojure\n(span \"foobar\"\n  (http-kit/get \"http://google.com/all-your-base\"\n                {:headers (trace/make-downstream-headers)}))\n```\n\nAs above, keep in mind that Ring already wraps a span, so you can do this pretty much anywhere within your app.\nThe function returns a `{str str}`, which is what most HTTP clients understand\n\n### Reporting\n\nThere are multiple reporters available.\n\nThe `logging` one\n```clojure\n(opencensus-clojure.reporting.logging/report)\n```\n\nThe Jaeger one\n```clojure\n(opencensus-clojure.reporting.jaeger/report \"my-service-name\")\n\n; allows you to specify the Thrift HTTP endpoint manually\n(opencensus-clojure.reporting.jaeger/report \"http://localhost:14268/api/traces\" \"my-service-name\")\n```\n\nThe Zipkin one\n```clojure\n(opencensus-clojure.reporting.zipkin/report \"my-service-name\")\n\n; allows you to specify the HTTP endpoint manually\n(opencensus-clojure.reporting.jaeger/report \"http://localhost:9411/api/v2/spans\" \"my-service-name\")\n```\n\nThe logging one is nice to figure out if your stuff is working in the first place if your Jaeger or Zipkin thing seems\nto not be. \n\nYou can launch a batteries included Jaeger thing via\n```shell\n$ docker run --rm -i \\\n  -e COLLECTOR_ZIPKIN_HTTP_PORT=9411 \\\n  -p5775:5775/udp -p6831:6831/udp -p6832:6832/udp \\\n  -p5778:5778 -p16686:16686 -p14268:14268 -p9411:9411 \\\n  jaegertracing/all-in-one:latest\n```\nIt should come up with a UI on `localhost:16686`, and you should see all your traces there.\n\nLaunching a local Zipkin handler is up to you.\n\n#### Configuration\n\nThe traces are probabilistic by default; you can configure the tracer to `p=1.0` via\n```clojure\n(opencensus-clojure.trace/configure-tracer {:probability 1.0})\n```\nto force sampling. The configuration function also takes\n- `max-annotations`\n- `max-attributes`\n- `max-links`\n- `max-message-events`\n\n## Disclaimer\n\nThis relies on \n- [opencensus-java](https://www.javadoc.io/doc/io.opencensus/opencensus-api/0.12.3)\n  - [github](https://github.com/census-instrumentation/opencensus-java)\n- single-threadedness for the duration of a span. I.e., your usual Ring + Jetty should work just fine.\n If you're doing futures inside your requests and try doing spans in said futures, it will probably\n get funny. Have done no testing there, so that way be dragons.\n Async Ring and other green thread stuff will probably get funny.\n OpenCensus supports directly passing in parent spans etc., and we can extend it to be \n async/threading-compatible if there's actual demand.\n\n# License\n\nCopyright © 2018 uSwitch\n\nDistributed under the Eclipse Public License, the same as Clojure.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuswitch%2Fopencensus-clojure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuswitch%2Fopencensus-clojure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuswitch%2Fopencensus-clojure/lists"}