Skip to content
This repository has been archived by the owner on Mar 26, 2024. It is now read-only.
/ dogstatsde Public archive

A StatsD (plus Datadog tag additions) client for Erlang

License

Notifications You must be signed in to change notification settings

WhoopInc/dogstatsde

Repository files navigation

Notice: This repository is no longer maintained as of 3/26/2024

Build Status Hex.pm

A dogstatsd client for Erlang

DogStatsD is Datadog's extension of StatsD. It adds tags to the metrics.

Configure

The defaults assume that you're running a statsd server on localhost (true if the agent is installed locally).

There are a number of configuration settings. You can either provide them as environment variables in ALL_CAPS or in an Erlang config file in all_lowercase.

name type default info
AGENT_ADDRESS string "localhost" Hostname or IP where we can send the StatsD UDP packets
AGENT_PORT integer 8125 Port that the StatsD agent is listening on
GLOBAL_PREFIX string "" Prefix to attach before all metric names. The . will be inserted for you
GLOBAL_TAGS map #{} Tags to attach to all metrics
SEND_METRICS boolean true Set to false when you're running tests to disable sending any metrics
VM_STATS boolean true Collect stats on the Erlang VM?
VM_STATS_DELAY integer 60000 Time in ms between collection Erlang VM stats
VM_STATS_SCHEDULER boolean true Collect stats on the scheduler?
VM_STATS_BASE_KEY string "erlang.vm" All the VM stats will begin with this prefix (after the GLOBAL_PREFIX if that is set)

Use

Erlang

  1. List dogstatsd in your rebar.config file
{dogstatsd, "<version>", {pkg, dogstatsde}}
  1. List the dogstatsd application in your *.app.src file

  2. Provide configuration as needed when starting up

  3. For VM stats, no action is needed -- they'll collect on their own as long as the application is running

  4. For custom metrics:

dogstatsd:gauge("users.active", UserCount, #{ shard => ShardId, version => Vsn })
  1. When pushing a lot of custom metrics, it can be beneficial to push them in chunks for efficiency, for example:
dogstatsd:gauge([{"users", UserTypeCount, #{ user_type => UserType }}
                 || {UserTypeCount, UserType} <- UserCounts]).

Elixir

For more details, see the example application in (examples/elixir)[examples/elixir]

  1. List dogstatsd dependency in your mix.exs file
{:dogstatsd, "~> <version>", hex: :dogstatsde}
  1. List :dogstatsd as an application in your mix.exs

  2. Provide configuration as needed when starting up

  3. For VM stats, no action is needed -- they'll collect on their own as long as the application is running

  4. For custom metrics:

:dogstatsd.gauge("users.active", user_count, %{ :shard => shard_id, :version => vsn })

VM Stats

If VM_STATS is not disabled, dogstatsd will periodically run erlang:statistics/1 and friends and collect data on the VM's performance:

name erlang call info
proc_count erlang:system_info(process_count)
proc_limit erlang:system_info(process_limit)
messages_in_queues process_info(Pid, message_queue_len) over all PIDs
modules length(code:all_loaded())
run_queue erlang:statistics(run_queue)
error_logger_queue_len process_info(Pid, message_queue_len) where Pid belongs to error_logger
memory.total erlang:memory()
memory.procs_userd erlang:memory()
memory.atom_used erlang:memory()
memory.binary erlang:memory()
memory.ets erlang:memory()
io.bytes_in erlang:statistics(io)
io.bytes_out erlang:statistics(io)
gc.count erlang:statistics(garbage_collection)
gc.words_reclaimed erlang:statistics(words_reclaimed)
reductions erlang:statistics(reductions)
scheduler_wall_time.active erlang:statistics(scheduler_wall_time) there are multiple schedulers, and the scheduler tag differentiates between them
scheduler_wall_time.total erlang:statistics(scheduler_wall_time) there are multiple schedulers, and the scheduler tag differentiates between them

screen-shot of VM stats in Datadog

Metric types

All metrics share the same signature:

-type metric_name() :: iodata().
-type metric_value() :: number().
-type metric_sample_rate() :: number().
-type metric_tags() :: map().

-spec MetricFunction(metric_name(), metric_value(), metric_sample_rate(), metric_tags()) -> ok.

Some metrics have aliases

name alias
gauge
increment counter
histogram
timing timer
set
  • The metric name is a string value with dots to separate levels of namespacing.
  • The sample rate is a number between [0.0,1.0]. This is the probability of sending a particular metric.
  • Tags are given as a map. The keys and values can be atoms, strings, or numbers.

Metric name and value are required. Sample rate defaults to 1.0. Tags defaults to an empty tag-set, but the value of GLOBAL_TAGS (which also defaults to an empty tag-set) is always merged with the passed tags.