dogstatsd

A Clojure wrapper over the official Datadog java-dogstatsd-client. It sends DogStatsD metrics, events, and service checks to a Datadog Agent.

Stack

Why

The other Clojure DogStatsD libraries are abandoned, and each one has its own UDP socket code. This library is a thin layer over Datadog's Java client. Datadog actively maintains this client. This layer gives UDS support, client-side aggregation, telemetry, and origin detection. The API keeps to Clojure conventions.

Installation

tools.deps (deps.edn):

net.clojars.savya/dogstatsd {:mvn/version "0.5.0"}

Leiningen (project.clj):

[net.clojars.savya/dogstatsd "0.5.0"]

Usage

(require '[dogstatsd.core :as dd])

;; Build a client (Closeable). Host and port use the SDK defaults unless set.
(def statsd
  (dd/client {:prefix "myapp"
              :constant-tags {:env "prod" :service "api"}}))

(dd/increment statsd :page.views)
(dd/increment statsd :page.views {:page "home"})
(dd/count     statsd :jobs.processed 5)
(dd/gauge     statsd :queue.depth 42)
(dd/histogram statsd :response.size 2048)
(dd/distribution statsd :request.latency 12.5)
(dd/timing    statsd :db.query 150)            ; milliseconds
(dd/with-timing [statsd :db.query]
  (run-query))                                  ; records elapsed milliseconds
(dd/set-metric statsd :users.active "user-123")

;; Tags: a map {:k "v"} -> k:v, or a seq of strings ["k:v" ...].
(dd/gauge statsd :temperature 20 {:region "eu" :unit "c"})

;; Sampling and per-call tag cardinality use a trailing options map.
(dd/count statsd :jobs.processed 5 {:queue "critical"}
          {:sample-rate 0.25 :cardinality :high})
(dd/increment statsd :page.views {:page "home"}
              {:sample-rate 0.5 :cardinality :low})

;; Backfilled measurements use Unix timestamps in seconds.
(dd/count-at statsd :jobs.processed 5 1710000000 {:queue "critical"})
(dd/gauge-at statsd :queue.depth 42 1710000000 nil
             {:cardinality :orchestrator})

;; Events and service checks.
(dd/event statsd "Deploy" "v1.2.3 shipped" {:alert-type :success
                                            :tags {:version "1.2.3"}})
(dd/service-check statsd "api.healthy" :ok {:message "all good"})

;; Closeable: prefer with-open for short-lived clients.
(with-open [c (dd/client {:host "localhost" :port 8125})]
  (dd/increment c :ping))

A Datadog Agent must listen for DogStatsD packets. The default port is UDP 8125.

Client options

Use :socket-path for a Unix datagram socket or :named-pipe for a Windows named pipe. :address accepts the SDK transport URLs (udp://, unix://, or unixstream://).

(dd/client {:socket-path "/var/run/datadog/dsd.socket"
            :telemetry? false
            :origin-detection? true
            :queue-size 8192
            :max-packet-size 8192
            :sender-workers 2
            :cardinality :low
            :error-handler #(println "DogStatsD send failed:" %)})

The builder also exposes :telemetry-host, :telemetry-port, :telemetry-address, :entity-id, :container-id, :timeout-ms, :connection-timeout-ms, :buffer-pool-size, :socket-buffer-size, :processor-workers, :blocking?, :telemetry-flush-interval-ms, :aggregation-flush-interval-ms, :aggregation-shards, and :thread-factory. Cardinality values are :default, :none, :low, :orchestrator, and :high.

API

fn	DogStatsD type
increment / decrement	counter ±1
count	counter by delta
count-at	timestamped counter by delta
gauge	gauge
gauge-at	timestamped gauge
histogram	histogram
distribution	distribution
timing	timer (ms)
with-timing	[client metric], [client metric tags], or [client metric tags options]; measure and record a body's elapsed time (ms)
set-metric	set
event	event
service-check	service check

Each metric fn takes the client, a metric name (keyword or string), an optional value, and optional tags. count, gauge, increment, decrement, timing, histogram, and distribution also accept a trailing options map. That map holds :sample-rate, :cardinality, or both. If you give a cardinality but no sample rate, the library sends a sample rate of 1.0 to the SDK.

with-timing takes a binding vector of [client metric], [client metric tags], or [client metric tags options], then evaluates the body and records its elapsed wall-clock time in milliseconds.

License

Copyright © 2026 Savyasachi

Distributed under the Eclipse Public License 2.0.