Profiling Ruby

DataKit can receive performance data reported by Datadog Ruby Continuous Profiler and send it toGuance. Ruby Profiler collects data such as CPU time, wall time, and object allocations.

Prerequisites¶

Install DataKit and enable the Profile collector.
Use CRuby 2.5 or later. CRuby 3.2.3 or later is recommended. JRuby and TruffleRuby are not currently supported.
Run the application in a supported Linux x86-64 or arm64 environment, including glibc- or musl-based distributions. Ruby Profiler does not support serverless environments.
Use the datadog gem. Version ~> 2.30 is recommended. Versions earlier than 2.30 also require pkg-config or pkgconf when compiling native extensions.

The exact compatibility range may change as the SDK is updated. Also refer to Ruby Profiler supported versions.

Enable the DataKit Profile Collector¶

Go to the conf.d/profile directory in the DataKit installation directory, copy profile.conf.sample, and rename it to profile.conf. The default configuration already includes the receiving endpoint used by the Ruby SDK:

[[inputs.profile]]
  endpoints = ["/profiling/v1/input"]
  body_size_limit_mb = 32

After restarting DataKit, the receiving address is:

http://<DataKit address>:9529/profiling/v1/input

Set the Agent base address in the Ruby SDK to http://<DataKit address>:9529. Do not append /profiling/v1/input to the address.

Install the Ruby SDK¶

Add the following to the application's Gemfile:

gem "datadog", "~> 2.30"

Then install the dependencies:

bundle install

To also enable automatic instrumentation for Ruby APM, refer to DDTrace Ruby for instructions on configuring the gem loading entry point.

Configure and Start the Profiler¶

Use Environment Variables¶

The following example sends Profile data to a local DataKit instance:

DD_PROFILING_ENABLED=true \
DD_TRACE_AGENT_URL=http://127.0.0.1:9529 \
DD_ENV=production \
DD_SERVICE=my-ruby-service \
DD_VERSION=1.0.0 \
DD_TAGS=team:apm,region:cn \
bundle exec ddprofrb exec ruby app.rb

Rails applications can be started with the same environment variables:

DD_PROFILING_ENABLED=true \
DD_TRACE_AGENT_URL=http://127.0.0.1:9529 \
DD_ENV=production \
DD_SERVICE=my-rails-service \
DD_VERSION=1.0.0 \
bundle exec ddprofrb exec bin/rails server

You can also configure the host and port separately by using DD_AGENT_HOST and DD_TRACE_AGENT_PORT:

DD_AGENT_HOST=127.0.0.1
DD_TRACE_AGENT_PORT=9529

DD_TRACE_AGENT_URL takes precedence over the host/port configuration. Do not configure conflicting target addresses at the same time. In a container or Kubernetes environment, if DataKit and the application are not in the same container, replace 127.0.0.1 with a DataKit address that the application can access.

Use Code Configuration¶

You can also configure the Profiler while the application starts. For example, a Rails application can add the following to an initializer:

require "datadog"

Datadog.configure do |c|
  c.agent.host = "127.0.0.1"
  c.agent.port = 9529
  c.profiling.enabled = true
  c.env = "production"
  c.service = "my-rails-service"
  c.version = "1.0.0"
  c.tags = { "team" => "apm", "region" => "cn" }
end

After adding the configuration code, using ddprofrb exec to start the application is still recommended so that the Profiler loads as early as possible. If the launcher is unavailable, load the Profiler at the very beginning of the application entry point:

require "datadog/profiling/preload"

Then start the application with its original command.

Common Configuration¶

Environment Variable	Default	Description
`DD_PROFILING_ENABLED`	`false`	Whether to enable Continuous Profiler. It must be set to `true` for the integration.
`DD_PROFILING_ALLOCATION_ENABLED`	`false`	Whether to collect object allocation data. Enabling this option increases runtime overhead. Evaluate it in a pre-production environment first.
`DD_PROFILING_MAX_FRAMES`	`400`	Maximum number of frames collected for each call stack.
`DD_PROFILING_EXPERIMENTAL_HEAP_ENABLED`	`false`	Whether to enable experimental heap analysis. Object allocation collection must also be enabled.
`DD_ENV`	None	Application deployment environment, such as `production` or `staging`.
`DD_SERVICE`	Inferred by the SDK	Service name. Explicitly setting it in production is recommended.
`DD_VERSION`	None	Application version.
`DD_TAGS`	None	Additional tags in `key:value` format, separated by commas.

The support scope and performance overhead of experimental features may change with SDK versions. Before enabling them, refer to Ruby Profiler configuration.

View Profiles¶

After the application starts, Ruby Profiler periodically reports data to DataKit. Wait one or two minutes, then view the corresponding data by service, env, and version on the Application Performance Monitoring -> Profile page in yourGuance workspace.

If the application also uses DDTrace Ruby for tracing, compatible SDK versions automatically include information that correlates Traces with Profiles. For tracing integration instructions, see DDTrace Ruby.

DataKit Metric Generation¶

DataKit recognizes language: ruby in data reported by the Ruby SDK, preserves the original Profile files and their metadata, and uploads them. Currently, generate_metrics extracts profiling_metrics only from Java, Go, and Python Profiles. Therefore, even when this option is set to true, Ruby Profiles do not generate additional profiling_metrics. This does not affect flame graphs or Profile details.

Troubleshooting¶

No Profile data: Verify that profile.conf is enabled and DD_PROFILING_ENABLED=true, then wait for at least one reporting interval.
Connection refused: Verify that the application can access <DataKit address>:9529. In a container, 127.0.0.1 refers only to the current container.
Address configuration does not take effect: Check whether DD_TRACE_AGENT_URL and DD_AGENT_HOST/DD_TRACE_AGENT_PORT are configured at the same time. Keep only one target configuration.
Native extension fails to load: Verify that you are using CRuby on a supported Linux architecture. For older gem versions, also verify that pkg-config or pkgconf is installed, and check the gem installation output and mkmf.log.
Request body is too large: If the DataKit log reports that a request exceeds the limit, increase body_size_limit_mb as needed and restart DataKit.
Sampling signal conflict: Ruby Profiler uses SIGPROF. If the application or another library also uses this signal, refer to Ruby Profiler troubleshooting.