Runtime Metrics

Overview

Runtime metrics monitor your application’s memory usage, garbage collection, and parallelization. Datadog tracing libraries automatically collect these metrics for supported environments and send them to the Datadog Agent.

These metrics help you identify bottlenecks, troubleshoot performance issues, and optimize resource utilization. By viewing runtime metrics alongside traces and logs, you gain comprehensive visibility into your application’s health and performance.

Compatibility

Runtime metrics are available for several programming languages and runtimes, with varying levels of support and configuration options.

  • Enabled By Default: Yes
  • Library Version: 0.29.0+
  • Support Level: GA
  • Generates runtime-id granularity: Yes
  • Runtimes: Java 8+
JMX metrics collection is not supported in AWS Lambda environments.
  • Enabled By Default: No
  • Library Version: 0.30.0+
  • Support Level: Preview
  • Generates runtime-id granularity: No
  • Runtimes: All supported Python versions
  • Enabled By Default: No
  • Library Version: 0.44.0+
  • Support Level: GA
  • Generates runtime-id granularity: No
  • Runtimes: All supported Ruby versions
You must add the dogstatsd-ruby gem to your application.
  • Enabled By Default: No
  • Library Version: 1.18.0+
  • Support Level: GA
  • Generates runtime-id granularity: Yes
  • Runtimes: All supported Go versions
  • Enabled By Default: No
  • Library Version: 3.0.0+
  • Support Level: GA
  • Generates runtime-id granularity: No
  • Runtimes: All supported Node.js versions
  • Enabled By Default: No
  • Library Version: 1.23.0+
  • Support Level: GA
  • Generates runtime-id granularity: Yes
  • Runtimes: .NET Framework 4.6.1+ and .NET Core 3.1+ (including .NET 5 and newer).

Permissions for Internet Information Services (IIS)

On .NET Framework, metrics are collected using performance counters. Users in non-interactive logon sessions (that includes IIS application pool accounts and some service accounts) must be added to the Performance Monitoring Users group to access counter data.

IIS application pools use special accounts that do not appear in the list of users. To add them to the Performance Monitoring Users group, look for IIS APPPOOL\<name of the pool>. For instance, the user for the DefaultAppPool would be IIS APPPOOL\DefaultAppPool.

This can be done either from the “Computer Management” UI, or from an administrator command prompt:

net localgroup "Performance Monitor Users" "IIS APPPOOL\DefaultAppPool" /add
Runtime metrics for PHP is not supported.
Runtime metrics for C++ is not supported.

Setup instructions

To set up runtime metrics, you need to configure both the Datadog Agent and your application.

1. Configure the Datadog Agent

Enable DogStatsD for the Agent. By default, the Datadog Agent is configured to ingest metrics with UDP over port 8125.

When running the Agent in containerized environments, additional configuration is required:

  1. Set dogstatsd_non_local_traffic: true in your main datadog.yaml configuration file, or set the environment variable DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true.
  2. Follow these container-specific setup instructions:
Docker
Kubernetes
Amazon ECS
ECS Fargate

  1. Set DD_SITE in the Datadog Agent to to ensure the Agent sends data to the correct Datadog location.

2. Configure your application

Configure runtime metrics in your application using environment variables. Some languages also support configuring runtime metrics directly in code.

Environment variables

Use the following environment variables to configure runtime metrics in your application:

DD_RUNTIME_METRICS_ENABLED
Default: true for Java, false for all other languages
Description: Enables the collection of runtime metrics. Metrics are sent to the Datadog agent, as configured for the instrumented application.
DD_AGENT_HOST
Default: localhost
Description: Sets the host address for the tracing library’s metric submission. Can be a hostname or an IP address.
DD_DOGSTATSD_PORT
Default: 8125
Description: Sets the port for the tracing library’s metric submission.

Code-based configuration

In addition to environment variables, some languages support configuring runtime metrics directly in code.

You can only enable runtime metrics with environment variables.

However, you can extend the metrics collected by adding custom JMX metrics. For more information, see JMX Integration documentation.

You can enable runtime metrics with environment variables or in code:

from ddtrace.runtime import RuntimeMetrics
RuntimeMetrics.enable()
This only applies if you are not using ddtrace-run

You can enable runtime metrics with environment variables or in code:

# config/initializers/datadog.rb
require 'datadog/statsd'
require 'datadog' # Use 'ddtrace' if you're using v1.x

Datadog.configure do |c|
  c.runtime_metrics.enabled = true

  # Optionally, you can configure the DogStatsD instance used for sending runtime metrics.
  # DogStatsD is automatically configured with default settings if `dogstatsd-ruby` is available.
  # You can configure with host and port of Datadog agent; defaults to 'localhost:8125'.
  c.runtime_metrics.statsd = Datadog::Statsd.new
end

You can enable runtime metrics with environment variables or in code:

// Basic configuration
tracer.Start(tracer.WithRuntimeMetrics())

// With custom DogStatsD address
tracer.Start(
  tracer.WithRuntimeMetrics(),
  tracer.WithDogstatsdAddr("custom-host:8125")
)

The WithDogstatsdAddr option allows you to specify a custom address for the DogStatsD server. Use the WithDogstatsdAddr (or WithDogstatsdAddress v1) option if your address differs from the default localhost:8125. (Available for 1.18.0+)

You can enable runtime metrics with environment variables or in code:

const tracer = require('dd-trace').init({
  // Other tracer options...
  runtimeMetrics: true
})

You can only enable runtime metrics with environment variables.

Dashboards

After setup is complete, you can view runtime metrics in:

  • The instrumented service’s details page
  • The flame graph Metrics tab
  • Default runtime dashboards
JVM Runtime Trace

Troubleshooting

  • To associate runtime metrics within flame graphs, ensure the env tag (case-sensitive) is set and matching across your environment.
  • For runtime metrics to appear on the service page when using Fargate, ensure that DD_DOGSTATSD_TAGS is set on your Agent task, and that the configured env tag matches the env of the instrumented service.

Data collected

Each supported language collects a set of runtime metrics that provide insights into memory usage, garbage collection, CPU utilization, and other performance indicators.

Further reading

PREVIEWING: guacbot/translation-pipeline