samsara.trackit — samsara/trackit-core 0.9.1

*registry* clj

all-metrics clj

(all-metrics)

(all-metrics registry)

Returns a list of all metrics with their current value and a formatted value

count-tracker clj

(count-tracker name)

It returns a function which traces the number of times it is called or the number of items seen. A counter is a monotonically increasing number. All counters are updated atomically.

Usage example:

;; create the counter (def track-orders (count-tracker "myapp.orders.processed"))

;; use the counter (defn mark-order-as-processed [& args] (track-orders) ;; increment and report the counter (comment do something else))

When called without arguments it atomically increments the counter by 1. If you call the function with a number will increment the counter by that number. Example:

;; create the counter (def track-order-items (count-tracker "myapp.items.processed"))

;; use the counter (defn mark-order-as-processed [{items :items :as order}] (track-order-items (count items)) ;; increment and report the counter (comment do something else))

distribution-tracker clj

(distribution-tracker name)

It returns a function which takes a value as parameter and it tracks its distribution. Whenever you are looking for an average, an histogram gives you more information. So rather than looking at:

The average search result is 120 items

with a distribution you get something like:

75% of all searches returned 100 or fewer results, while 95% got 200 or fewer.

usage:

;; initialize tracker (def track-search-results (distribution-tracker "search.results"))

;; track searches (defn my-search [query] (let [results (execute query) _ (track-search-results (count results)] results)))

get-metric clj

(get-metric name)

(get-metric registry name)

Returns current value of the given metric

namer clj

new-registry clj

(new-registry)

rate-tracker clj

(rate-tracker name)

It returns a function which tracks how often an event happens. It is useful to track things such as: number of request per second, number of db-query per second, number of orders per minute etc.

usage:

;; initialize tracker
(def track-request-rate (rate-tracker "myapp.user.requests"))

;; in your request handler
(defn request-handler [req]
  (track-request-rate)
  (comment handle the request))

If the step is bigger than 1 then you can specify a size:

;; in your request handler
(defn request-handler [req]
  (track-request-size-rate (get-size req))
  (comment handle the request))

remove-metric clj

(remove-metric name)

(remove-metric registry name)

Removes the given metric from the registry causing. After this call the given metric won't be reported any longer.

reset-registry! clj

(reset-registry!)

show-stats clj

(show-stats)

(show-stats format)

Prints the current list of metrics with their values. Optionally you can pass a parameter format which changes the level of information displayed for every metric. format can be: :short or :full, :short is the default.

(show-stats) ;; prints list of stats with short value (show-stats :full) ;; prints list of stats with detailed value

start-reporting! clj

(start-reporting! cfg)

(start-reporting! registry {:keys [jvm-metrics] :as cfg})

Initialize reporting to selected backend

time-tracker clj

track-count clj

(track-count name)

(track-count name count)

It increments a counter by the given value. If the counter doesn't exist it creates one. It returns the value passed. A counter is a monotonically increasing number. All counters are updated atomically.

Usage example:

;; use the counter (defn mark-order-as-processed [& args] (track-count "myapp.orders.processed") (comment do something else))

;; use the counter with a give increment (defn process-order [{items :items :as order}] (track-count "myapp.orders.items.count" (count items)) (comment do something else))

track-distribution clj

(track-distribution name value)

It tracks the distribution of a value, and it returns value. Whenever you are looking for an average, an histogram gives you more information. So rather than looking at:

The average search result is 120 items

with a distribution you get something like:

75% of all searches returned 100 or fewer results, while 95% got 200 or fewer.

usage:

;; track searches (defn my-search [query] (let [results (execute query)] (track-distribution "myapp.search.results" (count results)) results))

Typically the thing you want to track is going to be either a straight number or something countable. So rather than having to wrap the the result into a let, you can pass the "thing" you want to track as the value parameter. If it is a number it will use its value, if values is a seq, a collection or anything you can count on it, it will run (count value) or an exception will be raised. Finally the value will be returned as result of the function. The following code is equivalent to the previous one, but much clearer.

;; track searches (defn my-search [query] (track-distribution "myapp.search.results" (execute query)))

It returns the result of the body execution.

track-pass-count clj macro

(track-pass-count name & body)

It counts the number of time the body is executed. The increment is always by 1. A counter is a monotonically increasing number. All counters are updated atomically.

Usage example:

;; use the counter (defn mark-order-as-processed [& args] (track-pass-count "myapp.orders.processed" ;; count body executions (comment do something else)))

track-pass-rate clj macro

(track-pass-rate name & body)

It tracks the rate of the body execution. It is useful to track things such as: number of request per second, number of db-query per second, number of orders per minute etc.

usage:

;; in your request handler
(defn request-handler [req]
  (track-rate "myapp.user.requests"
    (comment handle the request)))

track-rate clj

(track-rate name)

(track-rate name count)

It tracks the rate of a give of value It is useful to track things such as: number of request per second, number of db-query per second, number of orders per minute etc.

usage:

;; in your request handler
(defn request-handler [req]
  (track-rate "myapp.user.requests")
  (comment handle the request))


;; track the number of doc indexed
(defn index-documents [documents]
  (track-rate "myapp.document.indexed" (count documents))
  (comment handle the request))

track-time clj macro

(track-time name & body)

It track the distribution of the time it takes to execute the body and the rate at which it is processed.

This is useful to measure things such as: the time it takes to query the database, or to process a request, or to send a request to another services. Anytime you what to know about how long it takes to run a part of your code use this tracker.

(track-time "myapp.db.search" (let [connection (get-connection db)] (db-query connection a-query)))

It returns the result of body execution.

track-value clj macro

(track-value name & body)

It tracks the current value of a function. This is useful to measure stats at regular intervals, such as the number of active users, the connection pool size, the number of pending requests etc. It is the same as track-value-of, it's just a convenience macro which wraps the body into a function.

;; initialize tracker (track-value "db.connection.pool.size" (get-current-pool-size db-pool))

Once initialized it will be reported at regular intervals, typically every 10s (reporter configuration) which means that every ~10s a call to the tracker-fn will be made.

track-value-of clj

(track-value-of name tracker-fn)

It tracks the current value of a function. This is useful to measure stats at regular intervals, such as the number of active users, the connection pool size, the number of pending requests etc.

;; initialize tracker (track-value-of "db.connection.pool.size" (fn [] (get-current-pool-size db-pool)))

Once initialized it will be reported at regular intervals, typically every 10s (reporter configuration) which means that every ~10s a call to the tracker-fn will be made.