A small Clojure library to wrap the libhoney-java client used to transit events to Honeycomb.
We realized we wrote the same code in several applications to integrate honeycomb.io into our application. This library was extracted for internal use, so we decided to publish it. It might be very opinionated and tailored to our usecases.
The following code creates a new instance of the Honeycomb Java Client:
(require '[maja.core :refer [initialize-honey])
(init-honeycomb {:write-key "xxxxxxx"
:dataset "my-ds-name"
:sample-rate 1})It is not Majas job to store the reference, your applications lifefycle needs to take care of this!
The library contains a middleware which starts a trace for all incoming HTTP requests. Subsequent spans will be added to that trace, too.
(require '[maja.core :refer [initialize-honey]
[maja.middleware :refer [wrap-honey-middleware]]])
(def honey (init-honeycomb {:write-key "xxxxxxx"
:dataset "my-ds-name"
:sample-rate 1}))
(defn wrap-honey-middleware [handler]
(if (some? honey)
(honey-middleware handler honey)
handler))It automatically traces the following fields:
| Field | Description |
|---|---|
| Timestamp | Timestamp of the HTTP call |
| duration_ms | Duration it took to process the HTTP call |
| method | The HTTP method (get, post, put...), lowercase |
| name | Defaults to "honey-middleware" |
| path | The HTTP path of the request |
| status | The HTTP status of the request |
| trace.span_id | A unique UUID |
| trace.trace_id | A UUID, shared with subsequent spans |
The parent trace_id and span_id are managed with scoping in the library. When a trace was started (e.g. by the middleware), you can call send-in-trace to "manually" add a trace with your desired fields to it:
(require '[maja.core :refer [send-in-trace]])
(send-in-trace {"name" "mail-rate-limit-hit"
"error" true}
honey-client)This event will be present in the whole trace and gets timestamped automatically.
Adding traces (and more nested spans) manually can show intent in the code, but it can also clutter and be repetitive. For this reason, Maja enables you to automatically trace Clojure functions with adding {:traced true} to their metadata. To enable this feature, you need to call the function wrap-all-trace-methods in the maja.core namespace. This function will scan all of your namespaces for functions with the correct metadata, and wrap them in a trace function using alter-var-root. Each call to these functions will create a new span in the active trace (or a new trace, if none is present), creating a hierarchy of your nested function calls with timestamps and duration of each function. This will integrate with traces started by the honey-middleware.
; Example for a traced Clojure function (which is present in the screenshot above)
(defn load-or-create-user! {:traced true} [email]
(:id
(or (db/user-id {:email email})
(conman/with-transaction [db/*db*]
(db/create-user! {:id (.toString (java.util.UUID/randomUUID))
:email email})
(db/user-id {:email email})))))
; Call this once upon intialization
(wrap-all-trace-methods honey-client)Copyright © 2021 lambdaschmiede GmbH
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at http://www.eclipse.org/legal/epl-2.0.
This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version, with the GNU Classpath Exception which is available at https://www.gnu.org/software/classpath/license.html.