百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
S

statsd-instrument

> 编程语言
开源

Ruby应用程序的StatsD客户端. 提供元编程方法将 StatsD 仪器输入您的代码.

592 stars0 点赞4 次浏览
访问官网GitHub

工具介绍

Ruby应用程序的StatsD客户端. 提供元编程方法将 StatsD 仪器输入您的代码.

StatsD client for Ruby apps

This is a ruby client for statsd (https://github.com/statsd/statsd). It provides a lightweight way to track and measure metrics in your application.

We call out to statsd by sending data over a UDP socket. UDP sockets are fast, but unreliable, there is no guarantee that your data will ever arrive at its location. In other words, fire and forget. This is perfect for this use case because it means your code doesn't get bogged down trying to log statistics. We send data to statsd several times per request and haven't noticed a performance hit.

For more information about StatsD, see the README of the StatsD project.

Configuration

It's recommended to configure this library by setting environment variables. The following environment variables are supported:

  • STATSD_ADDR: (default localhost:8125) The address to send the StatsD UDP datagrams to.

  • STATSD_IMPLEMENTATION: (default: datadog). The StatsD implementation you are using. statsd and datadog are supported. Some features are only available on certain implementations,

  • STATSD_ENV: The environment StatsD will run in. If this is not set explicitly, this will be determined based on other environment variables, like RAILS_ENV or ENV. The library will behave differently:

    • In the production and staging environment, the library will actually send UDP packets.
    • In the test environment, it will swallow all calls, but allows you to capture them for testing purposes. See below for notes on writing tests.
    • In development and all other environments, it will write all calls to the log (StatsD.logger, which by default writes to STDOUT).
  • STATSD_SAMPLE_RATE: (default: 1.0) The default sample rate to use for all metrics. This can be used to reduce the amount of network traffic and CPU overhead the usage of this library generates. This can be overridden in a metric method call.

  • STATSD_PREFIX: The prefix to apply to all metric names. This can be overridden in a metric method call.

  • STATSD_DEFAULT_TAGS: A comma-separated list of tags to apply to all metrics. (Note: tags are not supported by all implementations.)

  • STATSD_BUFFER_CAPACITY: (default: 5000) The maximum amount of events that may be buffered before emitting threads will start to block. Increasing this value may help for application generating spikes of events. However if the application emit events faster than they can be sent, increasing it won't help. If set to 0, batching will be disabled, and events will be sent in individual UDP packets, which is much slower.

  • STATSD_FLUSH_INTERVAL: (default: 1) Deprecated. Setting this to 0 is equivalent to setting STATSD_BUFFER_CAPACITY to 0.

  • STATSD_MAX_PACKET_SIZE: (default: 1472) The maximum size of UDP packets. If your network is properly configured to handle larger packets you may try to increase this value for better performance, but most network can't handle larger packets.

  • STATSD_BATCH_STATISTICS_INTERVAL: (default: "0") If non-zero, the BatchedUDPSink will track and emit statistics on this interval to the default sink for your environment. The current tracked statistics are:

    • statsd_instrument.batched_udp_sink.batched_sends: The number of batches sent, of any size.
    • statsd_instrument.batched_udp_sink.synchronous_sends: The number of times the batched udp sender needed to send a statsd line synchronously, due to the buffer being full.
    • statsd_instrument.batched_udp_sink.avg_buffer_length: The average buffer length, measured at the beginning of each batch.
    • statsd_instrument.batched_udp_sink.avg_batched_packet_size: The average per-batch byte size of the packet sent to the underlying UDPSink.
    • statsd_instrument.batched_udp_sink.avg_batch_length: The average number of statsd lines per batch.

Experimental aggregation feature

The aggregation feature is currently experimental and aims to improve the efficiency of metrics reporting by aggregating multiple metric events into a single sample. This reduces the number of network requests and can significantly decrease the overhead associated with high-frequency metric reporting.

This means that instead of sending each metric event individually, the library will aggregate multiple events into a single sample and send it to the StatsD server. Example:

Instead of sending counters in multiple packets like this:

my.counter:1|c
my.counter:1|c
my.counter:1|c

The library will aggregate them into a single packet like this:

my.counter:3|c

and for histograms/distributions:

my.histogram:1|h
my.histogram:2|h
my.histogram:3|h

The library will aggregate them into a single packet like this:

my.histogram:1:2:3|h

Enabling Aggregation

To enable metric aggregation, set the following environment variables:

  • STATSD_ENABLE_AGGREGATION: Set this to true to enable the experimental aggregation feature. Aggregation is disabled by default.
  • STATSD_AGGREGATION_INTERVAL: Specifies the interval (in seconds) at which aggregated metrics are flushed and sent to the StatsD server. For example, setting this to 2 will aggregate and send metrics every 2 seconds. Two seconds is also the default value if this environment variable is not set.

Please note that since aggregation is an experimental feature, it should be used with caution in production environments.

[!WARNING] This feature is only compatible with Datadog Agent's version >=6.25.0 && =7.25.0.

StatsD keys

StatsD keys look like 'admin.logins.api.success'. Dots are used as namespace separators.

Usage

You can either use the basic methods to submit stats over StatsD, or you can use the metaprogramming methods to instrument your methods with some basic stats (call counts, successes & failures, and timings).

StatsD.measure

Lets you benchmark how long the execution of a specific method takes.

ruby
# You can pass a key and a ms value
StatsD.measure('GoogleBase.insert', 2.55)

# or more commonly pass a block that calls your code
StatsD.measure('GoogleBase.insert') do
  GoogleBase.insert(product)
end

StatsD.increment

Lets you increment a key in statsd to keep a count of something. If the specified key doesn't exist it will create it for you.

ruby
# increments default to +1
StatsD.increment('GoogleBase.insert')
# you can also specify how much to increment the key by
StatsD.increment('GoogleBase.insert', 10)
# you can also specify a sample rate, so only 1/10 of events
# actually get to statsd. Useful for very high volume data
StatsD.increment('GoogleBase.insert', sample_rate: 0.1)

StatsD.gauge

A gauge is a single numerical value that tells you the state of the system at a point in time. A good example would be the number of messages in a queue.

ruby
StatsD.gauge('GoogleBase.queued', 12, sample_rate: 1.0)

Normally, you shouldn't update this value too often, and therefore there is no need to sample this kind metric.

StatsD.set

A set keeps track of the number of unique values that have been seen. This is a good fit for keeping track of the number of unique visitors. The value can be a string.

ruby
# Submit the customer ID to the set. It will only be counted if it hasn't been seen before.
StatsD.set('GoogleBase.customers', "12345", sample_rate: 1.0)

Because you are counting unique values, the results of using a sampling value less than 1.0 can lead to unexpected, hard to interpret results.

StatsD.histogram

Builds a histogram of numeric values.

ruby

StatsD.histogram('Order.value', order.value_in_usd.to_f, tags: { source: 'POS' })

Because you are counting unique values, the results of using a sampling value less than 1.0 can lead to unexpected, hard to interpret results.

Note: This is only supported by the beta datadog implementation.

StatsD.distribution

A modified gauge that submits a distribution of values over a sample period. Arithmetic and statistical calculations (percentiles, average, etc.) on the data set are performed server side rather than client side like a histogram.

ruby
StatsD.distribution('shipit.redis_connection', 3)

Note: This is only supported by the beta datadog implementation.

StatsD.event

An event is a (title, text) tuple that can be used to correlate metrics with something that occurred within the system. This is a good fit for instance to correlate response time variation with a deploy of the new code.

ruby
StatsD.event('shipit.deploy', 'started')

Note: This is only supported by the datadog implementation.

Events support additional metadata such as date_happened, hostname, aggregation_key, priority, source_type_name, alert_type.

StatsD.service_check

An event is a (check_name, status) tuple that can be used to monitor the status of services your application depends on.

ruby
StatsD.service_check('shipit.redis_connection', 'ok')

Note: This is only supported by the datadog implementation.

Service checks support additional metadata such as timestamp, hostname, message.

Metaprogramming Methods

As mentioned, it's most common to use the provided metaprogramming methods. This lets you define all of your instrumentation in one file and not litter your code with instrumentation details. You should enable a class for instrumentation by extending it with the StatsD::Instrument class.

ruby
GoogleBase.extend StatsD::Instrument

Then use the methods provided below to instrument methods in your class.

statsd_measure

This will measure how long a method takes to run, and submits the result to the given key.

ruby
GoogleBase.statsd_measure :insert, 'GoogleBase.insert'

statsd_count

This will increment the given key even if the method doesn't finish (ie. raises).

ruby
GoogleBase.statsd_count :insert, 'GoogleBase.insert'

Note how I used the 'GoogleBase.insert' key above when measuring this method, and I reused here when counting the method calls. StatsD automatically separates these two kinds of stats into namespaces so there won't be a key collision here.

statsd_count_if

This will only increment the given key if the method executes successfully.

ruby
GoogleBase.statsd_count_if :insert, 'GoogleBase.insert'

So now, if GoogleBase#insert raises an exception or returns false (ie. result == false), we won't increment the key. If you want to define what success means for a given method you can pass a block that takes the result of the method.

ruby
GoogleBase.statsd_count_if :insert, 'GoogleBase.insert' do |response|
  response.code == 200
end

In the above example we will only increment the key in statsd if the result of the block returns true. So the method is returning a Net::HTTP response and we're checking the status code.

statsd_count_success

Similar to statsd_count_if, except this will increment one key in the case of success and another key in the case of failure.

ruby
GoogleBase.statsd_count_success :insert, 'GoogleBase.insert'

So if this method fails execution (raises or returns false) we'll increment the failure key ('GoogleBase.insert.failure'), otherwise we'll increment the success key ('GoogleBase.insert.success'). Notice that we're modifying the given key before sending it to statsd.

Again you can pass a block to define what success means.

ruby
GoogleBase.statsd_count_success :insert, 'GoogleBase.insert' do |response|
  response.code == 200
end

Instrumenting Class Methods

You can instrument class methods, just like instance methods, using the metaprogramming methods. You simply have to configure the instrumentation on the singleton class of the Class you want to instrument.

ru

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Ruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言