Merge pull request #5531 from DataDog/ayan.khan/add-extended-heartbeat

gh-worker-dd-mergequeue-cf854d[bot] · p-datadog · khanayan123 · web-flow · commit 29f1a366c26c · 2026-04-01T19:14:42.000Z
feat(telemetry): implement app-extended-heartbeat event

Co-authored-by: p-datadog &lt;156273877+p-datadog@users.noreply.github.com&gt;
Co-authored-by: khanayan123 &lt;khanayan_123@hotmail.com&gt;
Co-authored-by: ayan.khan &lt;ayan.khan@datadoghq.com&gt;
diff --git a/lib/datadog/core/configuration/settings.rb b/lib/datadog/core/configuration/settings.rb
@@ -914,6 +914,19 @@ def initialize(*_)
             o.default 60.0
           end
 
+          # The interval in seconds when extended heartbeat must be sent.
+          #
+          # This method is used internally, for testing purposes only.
+          #
+          # @default `DD_TELEMETRY_EXTENDED_HEARTBEAT_INTERVAL` environment variable, otherwise `86400`.
+          # @return [Integer]
+          # @!visibility private
+          option :extended_heartbeat_interval_seconds do |o|
+            o.type :int
+            o.env Core::Telemetry::Ext::ENV_EXTENDED_HEARTBEAT_INTERVAL
+            o.default 86400
+          end
+
           # The interval in seconds when telemetry metrics are aggregated.
           # Should be a denominator of `heartbeat_interval_seconds`.
           #
diff --git a/lib/datadog/core/configuration/supported_configurations.rb b/lib/datadog/core/configuration/supported_configurations.rb
@@ -107,6 +107,7 @@ module Configuration
           "DD_TAGS",
           "DD_TELEMETRY_AGENTLESS_URL",
           "DD_TELEMETRY_DEPENDENCY_COLLECTION_ENABLED",
+          "DD_TELEMETRY_EXTENDED_HEARTBEAT_INTERVAL",
           "DD_TELEMETRY_HEARTBEAT_INTERVAL",
           "DD_TELEMETRY_LOG_COLLECTION_ENABLED",
           "DD_TELEMETRY_METRICS_AGGREGATION_INTERVAL",
diff --git a/lib/datadog/core/telemetry/component.rb b/lib/datadog/core/telemetry/component.rb
@@ -99,6 +99,7 @@ def initialize( # standard:disable Metrics/MethodLength
           @worker = Telemetry::Worker.new(
             enabled: @enabled,
             heartbeat_interval_seconds: settings.telemetry.heartbeat_interval_seconds,
+            extended_heartbeat_interval_seconds: settings.telemetry.extended_heartbeat_interval_seconds,
             metrics_aggregation_interval_seconds: settings.telemetry.metrics_aggregation_interval_seconds,
             emitter: Emitter.new(
               @transport,
@@ -108,6 +109,8 @@ def initialize( # standard:disable Metrics/MethodLength
             metrics_manager: @metrics_manager,
             dependency_collection: settings.telemetry.dependency_collection,
             logger: logger,
+            settings: settings,
+            agent_settings: agent_settings,
             shutdown_timeout: settings.telemetry.shutdown_timeout_seconds,
           )
 
diff --git a/lib/datadog/core/telemetry/event.rb b/lib/datadog/core/telemetry/event.rb
@@ -18,6 +18,7 @@ module Event
 require_relative 'event/base'
 require_relative 'event/app_client_configuration_change'
 require_relative 'event/app_closing'
+require_relative 'event/app_extended_heartbeat'
 require_relative 'event/app_dependencies_loaded'
 require_relative 'event/app_endpoints_loaded'
 require_relative 'event/app_heartbeat'
diff --git a/lib/datadog/core/telemetry/event/app_extended_heartbeat.rb b/lib/datadog/core/telemetry/event/app_extended_heartbeat.rb
@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'app_started'
+
+module Datadog
+  module Core
+    module Telemetry
+      module Event
+        # Telemetry class for the 'app-extended-heartbeat' event
+        class AppExtendedHeartbeat < AppStarted
+          def initialize(settings:, agent_settings:)
+            @configuration = configuration(settings, agent_settings)
+          end
+
+          def type
+            'app-extended-heartbeat'
+          end
+
+          def payload
+            {
+              configuration: @configuration,
+            }
+          end
+
+          def app_started?
+            false
+          end
+        end
+      end
+    end
+  end
+end
diff --git a/lib/datadog/core/telemetry/ext.rb b/lib/datadog/core/telemetry/ext.rb
@@ -7,6 +7,7 @@ module Ext
         ENV_ENABLED = 'DD_INSTRUMENTATION_TELEMETRY_ENABLED'
         ENV_METRICS_ENABLED = 'DD_TELEMETRY_METRICS_ENABLED'
         ENV_HEARTBEAT_INTERVAL = 'DD_TELEMETRY_HEARTBEAT_INTERVAL'
+        ENV_EXTENDED_HEARTBEAT_INTERVAL = 'DD_TELEMETRY_EXTENDED_HEARTBEAT_INTERVAL'
         ENV_METRICS_AGGREGATION_INTERVAL = 'DD_TELEMETRY_METRICS_AGGREGATION_INTERVAL'
         ENV_DEPENDENCY_COLLECTION = 'DD_TELEMETRY_DEPENDENCY_COLLECTION_ENABLED'
         ENV_INSTALL_ID = 'DD_INSTRUMENTATION_INSTALL_ID'
diff --git a/lib/datadog/core/telemetry/worker.rb b/lib/datadog/core/telemetry/worker.rb
@@ -27,6 +27,9 @@ def initialize(
           metrics_manager:,
           dependency_collection:,
           logger:,
+          settings:,
+          agent_settings:,
+          extended_heartbeat_interval_seconds:,
           enabled: true,
           shutdown_timeout: Workers::Polling::DEFAULT_SHUTDOWN_TIMEOUT,
           buffer_size: DEFAULT_BUFFER_MAX_SIZE
@@ -35,8 +38,11 @@ def initialize(
           @metrics_manager = metrics_manager
           @dependency_collection = dependency_collection
           @logger = logger
+          @settings = settings
+          @agent_settings = agent_settings
 
           @ticks_per_heartbeat = (heartbeat_interval_seconds / metrics_aggregation_interval_seconds).to_i
+          @ticks_per_extended_heartbeat = (extended_heartbeat_interval_seconds / metrics_aggregation_interval_seconds).to_i
           @current_ticks = 0
 
           # Workers::Polling settings
@@ -63,6 +69,7 @@ def initialize(
           self.buffer = buffer_klass.new(@buffer_size)
 
           @initial_event_once = Utils::OnlyOnceSuccessful.new(APP_STARTED_EVENT_RETRIES)
+          @extended_heartbeat_ticks = 0
         end
 
         attr_reader :logger
@@ -151,6 +158,13 @@ def perform(*events)
           end
 
           @current_ticks += 1
+          @extended_heartbeat_ticks += 1
+
+          if @extended_heartbeat_ticks >= @ticks_per_extended_heartbeat
+            @extended_heartbeat_ticks = 0
+            extended_heartbeat!
+          end
+
           return if @current_ticks < @ticks_per_heartbeat
 
           @current_ticks = 0
@@ -170,6 +184,12 @@ def heartbeat!
           send_event(Event::AppHeartbeat.new)
         end
 
+        def extended_heartbeat!
+          return if !enabled? || !sent_initial_event?
+
+          send_event(Event::AppExtendedHeartbeat.new(settings: @settings, agent_settings: @agent_settings))
+        end
+
         def started!
           return unless enabled?
 
diff --git a/sig/datadog/core/telemetry/event/app_extended_heartbeat.rbs b/sig/datadog/core/telemetry/event/app_extended_heartbeat.rbs
@@ -0,0 +1,16 @@
+module Datadog
+  module Core
+    module Telemetry
+      module Event
+        class AppExtendedHeartbeat < AppStarted
+          @configuration: ::Array[telemetry_configuration]
+
+          def initialize: (settings: untyped, agent_settings: Core::Configuration::AgentSettings) -> void
+          def type: () -> "app-extended-heartbeat"
+          def payload: () -> { configuration: ::Array[telemetry_configuration] }
+          def app_started?: () -> false
+        end
+      end
+    end
+  end
+end
diff --git a/sig/datadog/core/telemetry/ext.rbs b/sig/datadog/core/telemetry/ext.rbs
@@ -6,6 +6,7 @@ module Datadog
         ENV_ENABLED: ::String
         ENV_LOG_COLLECTION: ::String
         ENV_METRICS_ENABLED: ::String
+        ENV_EXTENDED_HEARTBEAT_INTERVAL: ::String
         ENV_HEARTBEAT_INTERVAL: ::String
         ENV_METRICS_AGGREGATION_INTERVAL: ::String
         ENV_INSTALL_ID: ::String
diff --git a/sig/datadog/core/telemetry/worker.rbs b/sig/datadog/core/telemetry/worker.rbs
@@ -18,14 +18,18 @@ module Datadog
         @buffer_size: Integer
         @dependency_collection: bool
         @ticks_per_heartbeat: Integer
+        @ticks_per_extended_heartbeat: Integer
         @current_ticks: Integer
+        @extended_heartbeat_ticks: Integer
         @logger: ::Logger
+        @settings: untyped
+        @agent_settings: Core::Configuration::AgentSettings
 
         attr_reader logger: ::Logger
         attr_reader initial_event: Telemetry::Event::AppStarted
 	attr_reader initial_event_once: Datadog::Core::Utils::OnlyOnceSuccessful
 
-        def initialize: (?enabled: bool, heartbeat_interval_seconds: Float, metrics_aggregation_interval_seconds: Float, emitter: Emitter, metrics_manager: MetricsManager, ?shutdown_timeout: Float | Integer, ?buffer_size: Integer, dependency_collection: bool, logger: ::Logger) -> void
+        def initialize: (?enabled: bool, heartbeat_interval_seconds: Float, extended_heartbeat_interval_seconds: Integer, metrics_aggregation_interval_seconds: Float, emitter: Emitter, metrics_manager: MetricsManager, settings: untyped, agent_settings: Core::Configuration::AgentSettings, ?shutdown_timeout: Float | Integer, ?buffer_size: Integer, dependency_collection: bool, logger: ::Logger) -> void
         def initialize_state: -> void
 
         def start: (Telemetry::Event::AppStarted initial_event) -> void
@@ -48,6 +52,8 @@ module Datadog
 
         def heartbeat!: () -> void
 
+        def extended_heartbeat!: () -> void
+
         def started!: () -> void
 
         def flush_events: (Array[Event::Base] events) -> void
diff --git a/spec/datadog/core/telemetry/component_spec.rb b/spec/datadog/core/telemetry/component_spec.rb
@@ -45,11 +45,14 @@
     allow(Datadog::Core::Telemetry::Worker).to receive(:new).with(
       logger: logger,
       heartbeat_interval_seconds: heartbeat_interval_seconds,
+      extended_heartbeat_interval_seconds: settings.telemetry.extended_heartbeat_interval_seconds,
       metrics_aggregation_interval_seconds: metrics_aggregation_interval_seconds,
       dependency_collection: dependency_collection,
       enabled: enabled,
       emitter: an_instance_of(Datadog::Core::Telemetry::Emitter),
       metrics_manager: anything,
+      settings: settings,
+      agent_settings: agent_settings,
       shutdown_timeout: shutdown_timeout_seconds
     ).and_return(worker)
 
diff --git a/spec/datadog/core/telemetry/event/app_extended_heartbeat_spec.rb b/spec/datadog/core/telemetry/event/app_extended_heartbeat_spec.rb
@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+require 'datadog/core/telemetry/event/app_extended_heartbeat'
+
+RSpec.describe Datadog::Core::Telemetry::Event::AppExtendedHeartbeat do
+  let(:settings) { Datadog::Core::Configuration::Settings.new }
+  let(:agent_settings) { Datadog::Core::Configuration::AgentSettingsResolver.call(settings) }
+  let(:event) { described_class.new(settings: settings, agent_settings: agent_settings) }
+
+  describe '#type' do
+    it { expect(event.type).to eq('app-extended-heartbeat') }
+  end
+
+  describe '#app_started?' do
+    it { expect(event.app_started?).to be(false) }
+  end
+
+  describe '#payload' do
+    subject(:payload) { event.payload }
+
+    it 'includes only configuration' do
+      expect(payload.keys).to eq([:configuration])
+    end
+
+    it 'includes a non-empty configuration array' do
+      expect(payload[:configuration]).to be_a(Array)
+      expect(payload[:configuration]).not_to be_empty
+    end
+
+    it 'reflects settings values at instantiation time' do
+      settings.service = 'my-service'
+      event = described_class.new(settings: settings, agent_settings: agent_settings)
+
+      expect(event.payload[:configuration]).to include(
+        hash_including(name: 'DD_SERVICE', value: 'my-service')
+      )
+    end
+
+    it 'picks up changes made after a prior instantiation' do
+      settings.service = 'before'
+      _old_event = described_class.new(settings: settings, agent_settings: agent_settings)
+
+      settings.service = 'after'
+      new_event = described_class.new(settings: settings, agent_settings: agent_settings)
+
+      expect(new_event.payload[:configuration]).to include(
+        hash_including(name: 'DD_SERVICE', value: 'after')
+      )
+    end
+  end
+end
diff --git a/spec/datadog/core/telemetry/worker_spec.rb b/spec/datadog/core/telemetry/worker_spec.rb
@@ -9,17 +9,22 @@
     described_class.new(
       enabled: enabled,
       heartbeat_interval_seconds: heartbeat_interval_seconds,
+      extended_heartbeat_interval_seconds: extended_heartbeat_interval_seconds,
       metrics_aggregation_interval_seconds: metrics_aggregation_interval_seconds,
       emitter: emitter,
       metrics_manager: metrics_manager,
       dependency_collection: dependency_collection,
       logger: logger,
+      settings: settings,
+      agent_settings: agent_settings,
     )
   end
 
   let(:enabled) { true }
   let(:heartbeat_interval_seconds) { 0.5 }
+  let(:extended_heartbeat_interval_seconds) { 86400 }
   let(:metrics_aggregation_interval_seconds) { 0.25 }
+  let(:settings) { Datadog::Core::Configuration::Settings.new }
   let(:metrics_manager) { instance_double(Datadog::Core::Telemetry::MetricsManager, flush!: [], disable!: nil) }
   let(:emitter) { instance_double(Datadog::Core::Telemetry::Emitter) }
   let(:dependency_collection) { false }
@@ -379,6 +384,60 @@
     end
   end
 
+  describe '#extended_heartbeat!' do
+    let(:heartbeat_interval_seconds) { 0.5 }
+    let(:extended_heartbeat_interval_seconds) { 1 }
+    let(:metrics_aggregation_interval_seconds) { 0.5 }
+
+    before do
+      allow(emitter).to receive(:request).and_return(response)
+    end
+
+    context 'before the initial event is sent' do
+      it 'does not send the extended heartbeat' do
+        received_extended_heartbeat = false
+        allow(emitter).to receive(:request).with(an_instance_of(Datadog::Core::Telemetry::Event::AppExtendedHeartbeat)) do
+          received_extended_heartbeat = true
+          response
+        end
+
+        worker.send(:extended_heartbeat!)
+
+        expect(received_extended_heartbeat).to be(false)
+      end
+    end
+
+    context 'after the initial event is sent' do
+      it 'fires after the configured interval' do
+        received_extended_heartbeat = false
+        allow(emitter).to receive(:request).with(an_instance_of(Datadog::Core::Telemetry::Event::AppExtendedHeartbeat)) do
+          received_extended_heartbeat = true
+          response
+        end
+
+        worker.start(initial_event)
+        try_wait_until { worker.sent_initial_event? }
+        try_wait_until { received_extended_heartbeat }
+
+        expect(received_extended_heartbeat).to be(true)
+      end
+
+      it 'resets the tick counter and fires repeatedly' do
+        fired_count = 0
+        allow(emitter).to receive(:request).with(an_instance_of(Datadog::Core::Telemetry::Event::AppExtendedHeartbeat)) do
+          fired_count += 1
+          response
+        end
+
+        worker.start(initial_event)
+        try_wait_until { worker.sent_initial_event? }
+        try_wait_until { fired_count >= 2 }
+
+        expect(fired_count).to be >= 2
+      end
+    end
+  end
+
   describe '#perform' do
     context 'when worker is started and immediately stopped' do
       # The test now is passing locally for me without modifications to
@@ -415,11 +474,14 @@ def mutex
           worker = worker_class.new(
             enabled: enabled,
             heartbeat_interval_seconds: heartbeat_interval_seconds,
+            extended_heartbeat_interval_seconds: extended_heartbeat_interval_seconds,
             metrics_aggregation_interval_seconds: metrics_aggregation_interval_seconds,
             emitter: emitter,
             metrics_manager: metrics_manager,
             dependency_collection: dependency_collection,
             logger: logger,
+            settings: settings,
+            agent_settings: agent_settings,
           )
 
           worker.perform
diff --git a/supported-configurations.json b/supported-configurations.json
@@ -700,6 +700,13 @@
         "default": "true"
       }
     ],
+    "DD_TELEMETRY_EXTENDED_HEARTBEAT_INTERVAL": [
+      {
+        "version": "A",
+        "type": "int",
+        "default": "86400"
+      }
+    ],
     "DD_TELEMETRY_HEARTBEAT_INTERVAL": [
       {
         "version": "B",
