dogstatsd

A small, idiomatic Clojure wrapper over the official Datadog java-dogstatsd-client for sending DogStatsD metrics, events, and service checks to a Datadog Agent.

Stack

Why

The existing Clojure DogStatsD libraries are abandoned and roll their own UDP socket. This one is a thin layer over Datadog's own actively-maintained Java client, so you get UDS support, client-side aggregation, telemetry, and origin detection for free - with a Clojure-shaped API.

Installation

tools.deps (deps.edn):

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

Leiningen (project.clj):

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

Usage

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

;; Build a client (Closeable). Defaults to localhost:8125.
(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/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 be listening for DogStatsD packets (UDP 8125 by default).

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)
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 containing :sample-rate and/or :cardinality. When cardinality is provided without a sample rate, the SDK receives a sample rate of 1.0.

License

Copyright © 2026 Savyasachi

Distributed under the Eclipse Public License 2.0.